@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/rhf/use-rhf-wizard-step.ts

@@ -12,10 +12,10 @@
  *
  * Inside a `<StepperNav>` the hook registers the step's validator with the wizard, so
  * Next (and Finish on a form-bearing last step) runs it: on success the values go to
- * `onValid` and the wizard advances; on failure react-hook-form shows its own inline
- * `<FormMessage>`s, focuses the first field in error, and the wizard stays put — and,
- * since the result carries no per-field errors, says its "fill in the required
- * fields" line so the button did not seem to do nothing. It also RETURNS the
+ * `onValid` and the wizard advances; on failure the bound fields show their inline
+ * messages, react-hook-form focuses the first field in error, and the wizard stays
+ * put — and, since the result carries no per-field errors, says its "fill in the
+ * required fields" line so the button did not seem to do nothing. It also RETURNS the
  * validator, for a nav of your own outside `<StepperNav>` (where there is no wizard
  * context to register with, so nothing is registered).
  *

package/src/rhf.ts

@@ -1,5 +1,7 @@
-// `@eifi1/ui-kit/rhf` — the react-hook-form adapter: Form, FormField, FormItem,
-// FormLabel, FormControl, FormDescription, FormMessage and useFormField.
+// `@eifi1/ui-kit/rhf` — the react-hook-form adapter: Form and the bound Rhf* fields (and
+// RhfField as the escape hatch). The shadcn scaffold they are built from (FormField,
+// FormItem, FormLabel, FormControl, FormDescription, FormMessage, useFormField) left the
+// surface in 0.35 (refactor audit 2026-10, API-6f; deprecated in 0.34).
 //
 // The only entry point in the package that requires `react-hook-form`, and an optional
 // peer for that reason: an app without a form library installs nothing for it. NOT

package/src/search/command-palette-labels.ts

@@ -0,0 +1,16 @@
+// The English words of ./command-palette, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./command-palette re-exports them.
+
+import type { CommandPaletteLabels } from "./command-palette";
+
+export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
+  placeholder: "Search…",
+  empty: "No results",
+  loading: "Searching…",
+  dialog: "Search",
+  error: "Search failed. Try again.",
+  clear: "Clear search",
+  submit: "Search",
+  close: "Close",
+};

package/src/search/command-palette.tsx

@@ -3,12 +3,15 @@ import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { CornerDownLeft, Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { FIELD_TOUCH_TEXT } from "../components/ui";
+import { FIELD_TOUCH_TEXT } from "../components/field-base";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
-import { useKitLabels } from "../i18n/kit-labels";
+import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
+import { isImeEnter } from "../lib/ime";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMAND_PALETTE_LABELS } from "./command-palette-labels";
 
 export interface CommandItem {
   id: string;
@@ -92,16 +95,8 @@ export interface CommandPaletteLabels {
   close?: string;
 }
 
-export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
-  placeholder: "Search…",
-  empty: "No results",
-  loading: "Searching…",
-  dialog: "Search",
-  error: "Search failed. Try again.",
-  clear: "Clear search",
-  submit: "Search",
-  close: "Close",
-};
+// Defined in ./command-palette-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_COMMAND_PALETTE_LABELS };
 
 /**
  * How tall the palette's rows are. `"compact"` (the default) is the desktop list the
@@ -200,22 +195,12 @@ interface CommandPaletteProps {
   fullScreenOnPhone?: boolean;
   /** Row height — see {@link CommandPaletteDensity}. Default `"compact"`. */
   density?: CommandPaletteDensity;
-  labels?: Partial<CommandPaletteLabels>;
+  labels?: LabelOverride<CommandPaletteLabels>;
 }
 
-/** Registers a global ⌘K / Ctrl-K shortcut that calls `onOpen`. */
-export function useCommandKey(onOpen: () => void): void {
-  useEffect(() => {
-    const handler = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && (e.key === "k" || e.key === "K")) {
-        e.preventDefault();
-        onOpen();
-      }
-    };
-    document.addEventListener("keydown", handler);
-    return () => document.removeEventListener("keydown", handler);
-  }, [onOpen]);
-}
+// Defined in ./use-command-key, so `GlobalSearch` can listen for ⌘K without loading the
+// palette before it is opened (0.34, MOD-1).
+export { useCommandKey } from "./use-command-key";
 
 /**
  * A ⌘K-style command palette: a top-centred modal with a search field and a
@@ -389,19 +374,21 @@ export function CommandPalette({
       e.preventDefault();
       setActive((i) => Math.max(i - 1, 0));
     } else if (e.key === "Enter") {
+      // The Enter that confirms an IME composition is the IME's (BUG-9).
+      if (isImeEnter(e)) return;
       e.preventDefault();
       if (dirty) commit(draft);
       else choose(flat[active]);
     }
   };
 
-  // Escape on the whole dialog, not only the field: once Tab has moved focus to a row
-  // (or a footer control), Escape used to do nothing at all.
+  // A layer on the kit's Escape stack while open (Wave 2, DUP-1), taken on the whole
+  // dialog, not only the field: once Tab has moved focus to a row (or a footer
+  // control), Escape used to do nothing at all. It closed without stopping the key, so
+  // a dialog the palette was opened from closed with it.
+  useDismissLayer(open, onClose);
   const onDialogKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === "Escape") {
-      e.preventDefault();
-      onClose();
-    }
+    takeEscape(e);
   };
 
   // Keep the active row scrolled into view.
@@ -438,10 +425,10 @@ export function CommandPalette({
         onKeyDown={onDialogKeyDown}
         data-fullscreen={isPhone || undefined}
         className={cn(
-          "flex w-full flex-col overflow-hidden bg-[var(--bg-surface)] outline-none",
+          "flex w-full flex-col overflow-hidden bg-surface outline-none",
           isPhone
             ? "h-full"
-            : "max-h-[70vh] max-w-xl rounded-xl border border-[var(--border)] shadow-2xl",
+            : "max-h-[70vh] max-w-xl rounded-xl border border-subtle shadow-2xl",
         )}
         // Full screen means edge to edge, so the notch, the home indicator and the
         // rounded corners are the panel's to keep clear of.
@@ -456,8 +443,8 @@ export function CommandPalette({
             : undefined
         }
       >
-        <div className="flex shrink-0 items-center gap-2 border-b border-[var(--border)] px-3">
-          <Search className="size-4 shrink-0 text-[var(--text-placeholder)]" />
+        <div className="flex shrink-0 items-center gap-2 border-b border-subtle px-3">
+          <Search className="size-4 shrink-0 text-placeholder" />
           <input
             ref={inputRef}
             role="combobox"
@@ -470,13 +457,13 @@ export function CommandPalette({
             placeholder={l.placeholder}
             enterKeyHint={submitMode ? "search" : undefined}
             className={cn(
-              "w-full bg-transparent py-3 outline-none placeholder:text-[var(--text-placeholder)] text-[var(--text-primary)]",
+              "w-full bg-transparent py-3 outline-none placeholder:text-placeholder text-primary",
               // 16px on a phone, or iOS zooms the page in on focus — and on any other
               // touch screen too (a tablet's popover), FIELD_TOUCH_TEXT (§10.1).
               isPhone ? "text-base" : cn("text-sm", FIELD_TOUCH_TEXT),
             )}
           />
-          {loading && <span className="shrink-0 text-caption text-[var(--text-placeholder)]">{l.loading}</span>}
+          {loading && <span className="shrink-0 text-caption text-placeholder">{l.loading}</span>}
           {fieldText !== "" && (
             <button
               type="button"
@@ -486,7 +473,7 @@ export function CommandPalette({
                 // Clearing starts the next query far more often than it ends this one.
                 inputRef.current?.focus();
               }}
-              className="shrink-0 rounded p-1 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+              className="shrink-0 rounded p-1 text-placeholder hover:text-secondary"
             >
               <X className="size-4" />
             </button>
@@ -499,7 +486,7 @@ export function CommandPalette({
                 commit(draft);
                 inputRef.current?.focus();
               }}
-              className="shrink-0 rounded p-1 text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              className="shrink-0 rounded p-1 text-secondary hover:text-primary"
             >
               <CornerDownLeft className="size-4" />
             </button>
@@ -508,7 +495,7 @@ export function CommandPalette({
             <button
               type="button"
               onClick={onClose}
-              className="-me-1 shrink-0 rounded px-1 py-2 text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+              className="-me-1 shrink-0 rounded px-1 py-2 text-sm text-secondary hover:text-primary"
             >
               {l.close ?? DEFAULT_COMMAND_PALETTE_LABELS.close}
             </button>
@@ -518,14 +505,14 @@ export function CommandPalette({
         {/* The status lines sit outside the listbox: a listbox owns options and groups,
             and "No results" is neither. */}
         {failed && !loading && (
-          <div role="alert" className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">
+          <div role="alert" className="px-3 py-6 text-center text-sm text-muted">
             {l.error ?? DEFAULT_COMMAND_PALETTE_LABELS.error}
           </div>
         )}
         {/* `results`, not `flat`: a group whose only row is its "Searching…" line is not
             an empty result. */}
         {!failed && results.length === 0 && !loading && (
-          <div className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">{l.empty}</div>
+          <div className="px-3 py-6 text-center text-sm text-muted">{l.empty}</div>
         )}
         {/* Listbox grouping: each group is a `role="group"` named by its heading, and
             the list markup in between is presentational so the listbox's children are
@@ -537,7 +524,7 @@ export function CommandPalette({
               <div
                 id={groupId(groupIndex)}
                 role="presentation"
-                className="px-3 pb-0.5 pt-2 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]"
+                className="px-3 pb-0.5 pt-2 text-micro font-semibold uppercase tracking-wide text-placeholder"
               >
                 {group}
               </div>
@@ -549,7 +536,7 @@ export function CommandPalette({
                         key={item.id}
                         role="presentation"
                         className={cn(
-                          "flex items-center gap-2.5 px-3 text-xs text-[var(--text-placeholder)]",
+                          "flex items-center gap-2.5 px-3 text-xs text-placeholder",
                           comfortable ? "min-h-11 py-2.5" : "py-2",
                         )}
                       >
@@ -575,14 +562,14 @@ export function CommandPalette({
                       "flex w-full items-center gap-2.5 px-3 text-start",
                       comfortable ? "min-h-11 py-2.5 text-base" : "py-2 text-sm",
                       isActive
-                        ? "bg-[var(--bg-active)] text-[var(--text-primary)]"
-                        : "text-[var(--text-secondary)]",
+                        ? "bg-active text-primary"
+                        : "text-secondary",
                     ),
                   };
                   const inner = (
                     <>
                       {item.icon && (
-                        <span className="flex size-4 shrink-0 items-center justify-center text-[var(--text-placeholder)]">
+                        <span className="flex size-4 shrink-0 items-center justify-center text-placeholder">
                           {item.icon}
                         </span>
                       )}
@@ -590,7 +577,7 @@ export function CommandPalette({
                         {item.label}
                       </span>
                       {item.hint && (
-                        <span data-private={redact || undefined} className="shrink-0 text-xs text-[var(--text-placeholder)]">
+                        <span data-private={redact || undefined} className="shrink-0 text-xs text-placeholder">
                           {item.hint}
                         </span>
                       )}
@@ -636,7 +623,7 @@ export function CommandPalette({
         </ul>
 
         {l.hint && (
-          <div className="border-t border-[var(--border)] px-3 py-1.5 text-caption text-[var(--text-placeholder)]">
+          <div className="border-t border-subtle px-3 py-1.5 text-caption text-placeholder">
             {l.hint}
           </div>
         )}

package/src/search/global-search-labels.ts

@@ -0,0 +1,13 @@
+// The English words of ./global-search, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./global-search re-exports them.
+
+import type { GlobalSearchLabels } from "./global-search";
+
+export const DEFAULT_GLOBAL_SEARCH_LABELS: GlobalSearchLabels = {
+  trigger: "Search",
+  placeholder: "Search or jump to…",
+  shortcut: (keys) => `Search (${keys})`,
+  suggestions: "Try",
+  results: "Results",
+};

package/src/search/global-search.tsx

@@ -1,15 +1,29 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { lazy, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { useHref, useInRouterContext, useNavigate } from "react-router";
 import { AlertCircle, Loader2, Search } from "lucide-react";
 import { Tooltip } from "../components/tooltip";
 import { TOPBAR_TRIGGER_CLASS } from "../shell/topbar-controls";
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
-import { CommandPalette, DEFAULT_COMMAND_PALETTE_LABELS, useCommandKey } from "./command-palette";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+// Types only from ./command-palette, gone from the built module: the palette loads late.
 import type { CommandItem, CommandPaletteDensity, CommandPaletteLabels } from "./command-palette";
+import { DEFAULT_COMMAND_PALETTE_LABELS } from "./command-palette-labels";
+import { useCommandKey } from "./use-command-key";
 import { createSearchIndex } from "./search-index";
 import type { SearchEntry, SearchIndexOptions } from "./search-index";
+import { DEFAULT_GLOBAL_SEARCH_LABELS } from "./global-search-labels";
+
+/**
+ * The palette, loaded when the search is first opened rather than with the top bar
+ * (0.34, MOD-1 of the refactor audit 2026-10): ~5.5 kB gzip of keksdose's and kastlan's
+ * entry chunks, for a dialog drawn only once somebody searches. A LITERAL relative
+ * `import()`, as the catalogue loaders are (i18n/languages.ts), so the library build keeps
+ * the module its own and an app's bundler splits it off.
+ */
+const LazyCommandPalette = lazy(() =>
+  import("./command-palette").then((module) => ({ default: module.CommandPalette })),
+);
 
 export interface GlobalSearchLabels {
   /** The trigger's accessible name, and the dialog's. */
@@ -25,13 +39,8 @@ export interface GlobalSearchLabels {
   results: string;
 }
 
-export const DEFAULT_GLOBAL_SEARCH_LABELS: GlobalSearchLabels = {
-  trigger: "Search",
-  placeholder: "Search or jump to…",
-  shortcut: (keys) => `Search (${keys})`,
-  suggestions: "Try",
-  results: "Results",
-};
+// Defined in ./global-search-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_GLOBAL_SEARCH_LABELS };
 
 /**
  * A place results come from that is not the static index — a server search, a
@@ -176,7 +185,7 @@ export interface GlobalSearchProps {
   triggerName?: "plain" | "withShortcut";
   /** The palette's row height — `CommandPalette`'s `density`. Default `"compact"`. */
   density?: CommandPaletteDensity;
-  labels?: Partial<GlobalSearchLabels>;
+  labels?: LabelOverride<GlobalSearchLabels>;
   /** Passed through to the palette (`empty`, `loading`, `error`, `hint`, …). */
   paletteLabels?: Partial<CommandPaletteLabels>;
 }
@@ -234,6 +243,9 @@ interface SourceResult {
  *
  * Inside a react-router tree it navigates with the router and builds its links with it;
  * outside one, pass `navigate` (or accept full page loads).
+ *
+ * Since 0.34 the palette's module loads on the first open (MOD-1), so the dialog appears a
+ * moment after the trigger or ⌘K: a test finds it with `await screen.findBy…`.
  */
 export function GlobalSearch(props: GlobalSearchProps) {
   // Two components rather than a conditional hook: `useNavigate` throws outside a
@@ -312,6 +324,13 @@ function GlobalSearchImpl({
     if (open && !queryControlled) setOwnQuery("");
   }
 
+  // The palette mounts on the first open — its module loads then — and stays mounted
+  // after, closed, as it always was (MOD-1): a closed palette keeps the last results, and
+  // a reopen over an owner-held query shows them at once, where a palette mounted anew
+  // would say "No results" through its debounce first.
+  const [paletteMounted, setPaletteMounted] = useState(open);
+  if (open && !paletteMounted) setPaletteMounted(true);
+
   const openSearch = useCallback(() => setOpen(true), [setOpen]);
   const noop = useCallback(() => {}, []);
   useCommandKey(shortcut ? openSearch : noop);
@@ -558,19 +577,26 @@ function GlobalSearchImpl({
               </button>
             </Tooltip>
           )}
-      <CommandPalette
-        open={open}
-        onClose={() => setOpen(false)}
-        search={provider}
-        revision={items}
-        query={query}
-        onQueryChange={setQuery}
-        searchOn={searchOn}
-        redactLabels={redactLabels}
-        fullScreenOnPhone={fullScreenOnPhone}
-        density={density}
-        labels={resolvedPaletteLabels}
-      />
+      {/* Nothing is drawn while the palette's module is on its way (a few milliseconds,
+          once per page load). A failed load is a chunk-load error for the app's error
+          boundary, as a lazy route's is. */}
+      {paletteMounted && (
+        <Suspense fallback={null}>
+          <LazyCommandPalette
+            open={open}
+            onClose={() => setOpen(false)}
+            search={provider}
+            revision={items}
+            query={query}
+            onQueryChange={setQuery}
+            searchOn={searchOn}
+            redactLabels={redactLabels}
+            fullScreenOnPhone={fullScreenOnPhone}
+            density={density}
+            labels={resolvedPaletteLabels}
+          />
+        </Suspense>
+      )}
     </>
   );
 }

package/src/search/search-index.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { foldForSearch } from "../lib/text-match";
 
 /**
  * The matcher behind {@link GlobalSearch} — pure, React-free, testable on its own.
@@ -107,14 +108,12 @@ const FIELD_FACTOR: Record<SearchMatchField, number> = { title: 3, keywords: 2,
 
 /**
  * Lower case, accents off, punctuation to spaces — the form both sides are compared in.
- * Exported so an app can normalise its own keys the same way.
+ * Exported so an app can normalise its own keys the same way. The fold is every kit
+ * list's {@link foldForSearch} (DUP-5, refactor audit 2026-10); the index adds the
+ * punctuation-to-space step its word split needs.
  */
 export function normalizeSearchText(text: string): string {
-  return text
-    .normalize("NFD")
-    .replace(/\p{M}+/gu, "")
-    .toLowerCase()
-    .replace(/ß/g, "ss")
+  return foldForSearch(text)
     .replace(/[^\p{L}\p{N}]+/gu, " ")
     .trim();
 }

package/src/search/use-command-key.ts

@@ -0,0 +1,22 @@
+import { useEffect } from "react";
+
+/**
+ * Registers a global ⌘K / Ctrl-K shortcut that calls `onOpen`.
+ *
+ * Its own module since 0.34 (MOD-1, refactor audit 2026-10): `GlobalSearch` listens for
+ * the shortcut from the moment the top bar mounts but loads the palette only when it is
+ * first opened, and a hook imported from command-palette.tsx would have brought the
+ * palette along with it. Still exported from command-palette.tsx, where it always was.
+ */
+export function useCommandKey(onOpen: () => void): void {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && (e.key === "k" || e.key === "K")) {
+        e.preventDefault();
+        onOpen();
+      }
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [onOpen]);
+}

package/src/settings/settings-card-classes.ts

@@ -0,0 +1,11 @@
+/**
+ * The settings cards' type scale, PasskeysSetting's: a small title and a muted line.
+ * Every kit setting card draws it — the account cards, `SettingsSection` and the
+ * `SettingsCardTitle` they share — so it lives with the card look, in settings/. It was in
+ * account/account-parts.ts, which made settings/ import account/ and account/ import
+ * settings/ (MOD-8, refactor audit 2026-10); account-parts re-exports it.
+ *
+ * @internal Not part of the barrel.
+ */
+export const CARD_TITLE_CLASS = "text-sm font-medium";
+export const CARD_DESCRIPTION_CLASS = "text-xs text-muted";

package/src/settings/settings-heading.tsx

@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
-import { CARD_TITLE_CLASS } from "../account/account-parts";
+import { CARD_TITLE_CLASS } from "./settings-card-classes";
 
 /** The heading a settings card's title becomes. */
 export type SettingsHeadingTag = "h2" | "h3" | "h4";

package/src/settings/settings-labels.ts

@@ -1,4 +1,4 @@
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 
 /**
  * The `settings` namespace (docs/settings-harmonization.md §4.3): the settings page's
@@ -82,6 +82,6 @@ export const DEFAULT_SETTINGS_LABELS: SettingsLabels = {
  * page title "<group> · Settings · <app>" (settings contract §3.1), without restating
  * the namespace and its defaults (Kurvenschmiede's 0.31 adoption).
  */
-export function useSettingsLabels(labels?: Partial<SettingsLabels>): SettingsLabels {
+export function useSettingsLabels(labels?: LabelOverride<SettingsLabels>): SettingsLabels {
   return useKitLabels("settings", DEFAULT_SETTINGS_LABELS, labels);
 }

package/src/settings/settings-layout.tsx

@@ -1,8 +1,11 @@
-import { useCallback, useId, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import type { ReactElement, ReactNode } from "react";
 import { Link, useHref, useLocation } from "react-router";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { Button, Card, EmptyState, Tabs } from "../components/ui";
+import { Button } from "../components/button";
+import { Card } from "../components/card";
+import { EmptyState } from "../components/empty-state";
+import { Tabs } from "../components/tabs";
 import { FOCUS_RING } from "../components/focus-ring";
 import { Chip } from "../components/chip";
 import { List, ListItem } from "../components/list";
@@ -10,7 +13,7 @@ import type { ListItemLinkProps } from "../components/list";
 import { PageHeader } from "../components/page-header";
 import { SearchField } from "../components/search-field";
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { createSearchIndex } from "../search/search-index";
 import type { SearchEntry } from "../search/search-index";
 import {
@@ -70,12 +73,44 @@ export interface SettingsLayoutProps<G extends string> {
    */
   phoneFooter?: ReactNode;
   /** Prop > `<UiKitProvider labels={{ settings }}>` > English. */
-  labels?: Partial<SettingsLabels>;
+  labels?: LabelOverride<SettingsLabels>;
   /** See {@link SettingsLayoutMode}. Default `"auto"`: the screen decides. */
   layout?: SettingsLayoutMode;
+  /**
+   * The app's name, the last part of the window's title: "Security · Settings ·
+   * Kastlan" (§3.1). Left out, the title ends at the page: "Security · Settings".
+   */
+  appName?: string;
+  /**
+   * The window's title (`document.title`, §3.1) — round 0.34 C8, KS U7. By default the
+   * layout writes "<group> · <page> · <appName>" while a group is open and
+   * "<page> · <appName>" on the phone's list, and puts back the title it found when it
+   * unmounts. `<page>` is `title` when that is a string, else `labels.title`.
+   *
+   * A function writes another order or another separator from the same parts; `false`
+   * leaves `document.title` to the app. Kastlan's `SettingsChrome` and Kurvenschmiede's
+   * `GroupTitle` were this effect written by hand, and Kurvenschmiede's admin page, on
+   * the same layout, had none — every admin section was titled "Kurvenschmiede".
+   */
+  documentTitle?: false | ((parts: SettingsDocumentTitleParts) => string);
   className?: string;
 }
 
+/** What {@link SettingsLayoutProps.documentTitle} is given to write the window's title. */
+export interface SettingsDocumentTitleParts {
+  /** The open group's name, or `null` on the phone's list of groups. */
+  group: string | null;
+  /** The page: `title` when it is a string, else `labels.title` ("Settings"). */
+  page: string;
+  /** The `appName` prop, or `undefined`. */
+  appName: string | undefined;
+}
+
+/** "Security · Settings · Kastlan" (§3.1); a part that is missing is left out. */
+function defaultDocumentTitle({ group, page, appName }: SettingsDocumentTitleParts): string {
+  return [group, page, appName].filter((part): part is string => Boolean(part)).join(" · ");
+}
+
 interface Searchable<G extends string> extends SearchEntry {
   anchor: string;
   settingsGroup: G;
@@ -118,6 +153,8 @@ export function SettingsLayout<G extends string>({
   phoneFooter,
   labels: labelsProp,
   layout = "auto",
+  appName,
+  documentTitle,
   className,
 }: SettingsLayoutProps<G>): ReactElement {
   const labels = useKitLabels("settings", DEFAULT_SETTINGS_LABELS, labelsProp);
@@ -200,6 +237,28 @@ export function SettingsLayout<G extends string>({
   };
 
   const pageTitle = title ?? labels.title;
+
+  // The window's title (§3.1). Computed to a string during render so the effect below
+  // runs when the words change, not whenever an inline `documentTitle` function is new.
+  // Each run puts back the title it found before writing its own, so a group switch
+  // ends where it began and the unmount leaves the title the page had before settings.
+  const windowTitle =
+    documentTitle === false
+      ? null
+      : (documentTitle ?? defaultDocumentTitle)({
+          group: group === null ? null : (groupById.get(group)?.title ?? null),
+          page: typeof title === "string" ? title : labels.title,
+          appName,
+        });
+  useEffect(() => {
+    if (windowTitle === null) return;
+    const before = document.title;
+    document.title = windowTitle;
+    return () => {
+      document.title = before;
+    };
+  }, [windowTitle]);
+
   const pageClass = cn("mx-auto w-full space-y-4 p-4 md:p-6", width === "7xl" ? "max-w-7xl" : "max-w-6xl", className);
 
   const searchField = showSearch ? (
@@ -267,7 +326,7 @@ export function SettingsLayout<G extends string>({
                 e.preventDefault();
                 route.back();
               }}
-              className={cn("-ms-1 inline-flex items-center gap-0.5 self-start rounded-md pe-1 text-sm font-medium text-[var(--text-muted)] hover:text-[var(--text-primary)]", FOCUS_RING)}
+              className={cn("-ms-1 inline-flex items-center gap-0.5 self-start rounded-md pe-1 text-sm font-medium text-muted hover:text-primary", FOCUS_RING)}
             >
               <ChevronLeft aria-hidden className="size-4 rtl:-scale-x-100" />
               {pageTitle}
@@ -293,7 +352,7 @@ export function SettingsLayout<G extends string>({
                   leading={
                     <span
                       aria-hidden
-                      className="flex size-8 shrink-0 items-center justify-center rounded-md bg-[var(--bg-surface-2)] text-[var(--text-secondary)] [&_svg]:size-4"
+                      className="flex size-8 shrink-0 items-center justify-center rounded-md bg-surface-2 text-secondary [&_svg]:size-4"
                     >
                       {g.icon}
                     </span>

package/src/settings/settings-section.tsx

@@ -1,12 +1,12 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
-import { Card } from "../components/ui";
-import type { CardTone } from "../components/ui";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import { Card } from "../components/card";
+import type { CardTone } from "../components/card";
 import { cn } from "../lib/cn";
-import { CARD_DESCRIPTION_CLASS, CARD_TITLE_CLASS } from "../account/account-parts";
+import { CARD_DESCRIPTION_CLASS, CARD_TITLE_CLASS } from "./settings-card-classes";
 import { SettingsHeading, useSettingsHeadingLevel } from "./settings-heading";
 import { useSettingsLayout } from "./settings-context";
 
-export interface SettingsSectionProps extends Omit<ComponentPropsWithoutRef<"div">, "title" | "id"> {
+export interface SettingsSectionProps extends Omit<ComponentPropsWithRef<"div">, "title" | "id"> {
   /** The card's DOM id — the catalogue entry's `anchor`, the `?focus=` target. */
   anchor: string;
   /** The card's name: a heading at the layout's level (`h3` by default). */