@eifi1/ui-kit 0.33.1 → 0.34.0

package/src/shell/topbar-action-menu.tsx

@@ -2,7 +2,7 @@ import { useId, useLayoutEffect, useRef } from "react";
 import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
 import { Link } from "react-router";
 import { cn } from "../lib/cn";
-import { HoverMenu } from "../components/hover-menu";
+import { HoverMenu, type HoverMenuProps } from "../components/hover-menu";
 import { MenuItem } from "../components/menu-item";
 import type { MenuItemTone } from "../components/menu-item";
 import { StatusDot } from "../components/status-dot";
@@ -68,7 +68,7 @@ export type TopBarMenuEntry =
        *
        * The menu-wide `heading` prop is the panel's title, drawn once above everything;
        * with group headings it is usually redundant (two stacked caps lines read as one),
-       * and the trigger's `ariaLabel` already names the menu.
+       * and the trigger's `aria-label` already names the menu.
        */
       kind: "heading";
       key: string;
@@ -179,6 +179,23 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
   if (stops.some((el) => el !== from && from.compareDocumentPosition(el) & way)) e.stopPropagation();
 }
 
+/**
+ * Names the trigger and the menu: one of the two spellings is required (API-1, refactor
+ * audit 2026-10). `aria-label` wins when both are given. OptionSwitcherMenu has the same
+ * type; both become a plain required `aria-label` when `ariaLabel` goes in 0.35.
+ */
+type RequiredMenuName =
+  | {
+      "aria-label": string;
+      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
+      ariaLabel?: string;
+    }
+  | {
+      "aria-label"?: string;
+      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
+      ariaLabel: string;
+    };
+
 /**
  * A top-bar icon button that opens a {@link HoverMenu} of actions and/or links,
  * with an optional uppercase heading and divider rules. Generic glue over the
@@ -202,7 +219,8 @@ export function TopBarActionMenu({
   trigger,
   triggerClassName,
   href,
-  ariaLabel,
+  "aria-label": ariaLabelAttr,
+  ariaLabel: ariaLabelProp,
   heading,
   header,
   entries,
@@ -226,11 +244,11 @@ export function TopBarActionMenu({
    * INSIDE the kit's button, which keeps the wiring: `aria-haspopup`, `aria-expanded`,
    * the toggle, the keyboard. `open` is there for a chevron that turns.
    *
-   * The button is named by `ariaLabel` followed by any readable text in the face — a
+   * The button is named by `aria-label` followed by any readable text in the face — a
    * `UserAvatar` `badge` label reaches a screen reader that way ("Account menu 3
    * unread"), where an `aria-label` on the button would have hidden it. A
    * `UserAvatar`'s initials are `aria-hidden`, so the person's name is only in the
-   * name if `ariaLabel` carries it ("Marcel Eifert, account menu").
+   * name if `aria-label` carries it ("Marcel Eifert, account menu").
    */
   trigger?: (state: { open: boolean }) => ReactNode;
   /** Extra classes for the trigger button — `rounded-full` round an avatar. */
@@ -243,12 +261,10 @@ export function TopBarActionMenu({
    * row, so the rows stay reachable by keyboard. A tap on a touch screen follows the
    * link — so use it where the destination offers everything the menu does. Rendered as
    * an `<a>` (the router's `Link`) with `aria-haspopup="menu"` and `aria-expanded`,
-   * named by `ariaLabel`: a link inside the kit's button would be interactive content
+   * named by `aria-label`: a link inside the kit's button would be interactive content
    * inside interactive content.
    */
   href?: string;
-  /** Names the trigger and the menu. */
-  ariaLabel: string;
   heading?: string;
   /** A non-interactive identity block above the rows. */
   header?: TopBarMenuHeader;
@@ -267,17 +283,20 @@ export function TopBarActionMenu({
   footer?: ReactNode | ((close: () => void) => ReactNode);
   /** Wraps the footer in a `<nav>` with this name ("Legal"). Without it, a plain block. */
   footerLabel?: string;
-  /** Which edge of the trigger the panel lines up with (see `HoverMenu`). Default `end`. */
-  align?: "start" | "end" | "left" | "right";
+  /** Which edge of the trigger the panel lines up with (see `HoverMenu`, whose type this
+   *  is: `left`/`right` are deprecated 0.34). Default `end`. */
+  align?: HoverMenuProps["align"];
   panelClassName?: string;
-}) {
+} & RequiredMenuName) {
+  // The DOM spelling wins; `ariaLabel` is the fallback for call sites not moved yet.
+  const ariaLabel = ariaLabelAttr ?? ariaLabelProp;
   // Names the groups' headings for `aria-labelledby`. Positional rather than from the
   // entry's `key`, which is the caller's text and may hold a space — and a space in
   // `aria-labelledby` is a list separator.
   const uid = useId();
   return (
     <HoverMenu
-      ariaLabel={ariaLabel}
+      aria-label={ariaLabel}
       align={align}
       trigger={({ open, toggle, close }) => {
         // One element for both kinds: the router's link when `href` is set, else the
@@ -326,7 +345,7 @@ export function TopBarActionMenu({
         const footerBody = typeof footer === "function" ? footer(close) : footer;
         const headerExtra = typeof header?.extra === "function" ? header.extra(close) : header?.extra;
         const footerClass =
-          "flex flex-wrap gap-x-3 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-[length:var(--focus-ring-width)] [&_a:focus-visible]:ring-[var(--brand)]";
+          "flex flex-wrap gap-x-3 gap-y-1 text-xs text-muted [&_a:hover]:text-primary [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-focus [&_a:focus-visible]:ring-brand";
         /** One action or link row — loose, or inside a heading's group. */
         const row = (entry: RowEntry) => (
           <li key={entry.key}>
@@ -365,16 +384,16 @@ export function TopBarActionMenu({
           // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a Tab bubbling up from a row or footer link, see keepTabInsidePanel
           <ul className={cn("py-1", panelClassName)} onKeyDown={keepTabInsidePanel}>
             {header && (
-              <MenuSection className="mb-1 border-b border-[var(--border)] px-3 py-2">
-                <div className="truncate text-sm font-medium text-[var(--text-primary)]">{header.title}</div>
+              <MenuSection className="mb-1 border-b border-subtle px-3 py-2">
+                <div className="truncate text-sm font-medium text-primary">{header.title}</div>
                 {header.subtitle != null && (
-                  <div className="truncate text-xs text-[var(--text-muted)]">{header.subtitle}</div>
+                  <div className="truncate text-xs text-muted">{header.subtitle}</div>
                 )}
                 {headerExtra != null && headerExtra !== false && <div className="mt-1">{headerExtra}</div>}
               </MenuSection>
             )}
             {heading && (
-              <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-placeholder">
                 {heading}
               </li>
             )}
@@ -382,7 +401,7 @@ export function TopBarActionMenu({
               if (block.kind === "loose") {
                 const entry = block.entry;
                 if (entry.kind === "divider") {
-                  return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+                  return <li key={entry.key} className="my-1 border-t border-subtle" />;
                 }
                 return row(entry);
               }
@@ -397,7 +416,7 @@ export function TopBarActionMenu({
                     id={headingId}
                     role="presentation"
                     className={cn(
-                      "px-3 pb-0.5 text-caption font-semibold uppercase tracking-wide text-[var(--text-muted)] [overflow-wrap:anywhere]",
+                      "px-3 pb-0.5 text-caption font-semibold uppercase tracking-wide text-muted [overflow-wrap:anywhere]",
                       tight ? "pt-1" : "pt-2.5",
                     )}
                   >
@@ -411,7 +430,7 @@ export function TopBarActionMenu({
             })}
             {children?.(close)}
             {footerBody != null && footerBody !== false && (
-              <MenuSection className="mt-1 border-t border-[var(--border)] px-3 py-2">
+              <MenuSection className="mt-1 border-t border-subtle px-3 py-2">
                 {footerLabel ? (
                   <nav aria-label={footerLabel} className={footerClass}>
                     {footerBody}

package/src/shell/topbar-controls.tsx

@@ -9,17 +9,17 @@ import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
 /** Shared square icon-button styling for top-bar triggers, so app-owned controls
  *  (account/feedback menus) line up with the shared ones. */
 export const TOPBAR_TRIGGER_CLASS =
-  "size-9 rounded-md flex items-center justify-center text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:bg-[var(--bg-hover)]";
+  "size-9 rounded-md flex items-center justify-center text-secondary hover:text-primary hover:bg-hover";
 
 /** Shared row styling for the top-bar hover-menu items. `text-start`, so a label that
  *  wraps aligns to the reading edge in RTL too. */
 export const TOPBAR_MENU_ITEM_CLASS =
-  "flex w-full items-center justify-between gap-3 px-3 py-2 text-sm text-start text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]";
+  "flex w-full items-center justify-between gap-3 px-3 py-2 text-sm text-start text-secondary hover:bg-hover";
 
 /** The small uppercase heading row the top-bar menus share (`heading`). */
 function MenuHeading({ children }: { children: string }) {
   return (
-    <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+    <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-placeholder">
       {children}
     </li>
   );
@@ -29,6 +29,7 @@ function MenuHeading({ children }: { children: string }) {
 export function ThemeToggle({
   mode,
   onToggle,
+  "aria-label": ariaLabelAttr,
   ariaLabel,
   title,
   className,
@@ -36,13 +37,16 @@ export function ThemeToggle({
   mode: ThemeMode;
   onToggle: () => void;
   /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
+  "aria-label"?: string;
+  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
+   *  Names the control only when `aria-label` is absent. */
   ariaLabel?: string;
   title?: string;
   className?: string;
 }) {
-  // This had no default at all, so a toggle rendered without `ariaLabel` was an
+  // This had no default at all, so a toggle rendered without `aria-label` was an
   // icon button with no name — a reader heard "button" and nothing else.
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { theme: ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { theme: ariaLabelAttr ?? ariaLabel });
   const Icon = mode === "dark" ? Moon : Sun;
   return (
     <Tooltip label={title} portal>
@@ -65,6 +69,7 @@ export function PaletteMenu({
   activeId,
   mode,
   onSelect,
+  "aria-label": ariaLabelAttr,
   ariaLabel,
   heading,
 }: {
@@ -73,15 +78,18 @@ export function PaletteMenu({
   mode: ThemeMode;
   onSelect: (id: string) => void;
   /** Default: `topBar.palette` from the {@link UiKitProvider}, else English. */
+  "aria-label"?: string;
+  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
+   *  Names the control only when `aria-label` is absent. */
   ariaLabel?: string;
   /** Optional small heading row above the list. */
   heading?: string;
 }) {
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { palette: ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { palette: ariaLabelAttr ?? ariaLabel });
   const activeName = palettes.find((p) => p.id === activeId)?.name ?? activeId;
   return (
     <HoverMenu
-      ariaLabel={labels.palette}
+      aria-label={labels.palette}
       trigger={({ toggle }) => (
         <Tooltip label={activeName} portal>
           <button
@@ -131,13 +139,13 @@ export function PaletteMenu({
                     </span>
                     <span className="flex min-w-0 flex-col text-start">
                       <span className="truncate">{p.name}</span>
-                      <span className="truncate text-caption text-[var(--text-placeholder)]">
+                      <span className="truncate text-caption text-placeholder">
                         {p.blurb}
                       </span>
                     </span>
                   </span>
                   {activeId === p.id && (
-                    <Check className="size-4 shrink-0 text-[var(--text-secondary)]" />
+                    <Check className="size-4 shrink-0 text-secondary" />
                   )}
                 </button>
               </li>
@@ -169,6 +177,7 @@ export function LanguageMenu({
   options,
   current,
   onChange,
+  "aria-label": ariaLabelAttr,
   ariaLabel,
   heading,
 }: {
@@ -176,16 +185,19 @@ export function LanguageMenu({
   current: string | undefined;
   onChange: (code: string) => void;
   /** Default: `topBar.language` from the {@link UiKitProvider}, else English. */
+  "aria-label"?: string;
+  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
+   *  Names the control only when `aria-label` is absent. */
   ariaLabel?: string;
   /** Optional small heading row above the list — as on `TopBarActionMenu`,
    *  `OptionSwitcherMenu` and `PaletteMenu`. */
   heading?: string;
 }) {
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabelAttr ?? ariaLabel });
   const active = options.find((o) => o.code === current);
   return (
     <HoverMenu
-      ariaLabel={labels.language}
+      aria-label={labels.language}
       trigger={({ toggle }) => (
         <Tooltip label={active?.label ?? labels.language} portal>
           <button
@@ -228,7 +240,7 @@ export function LanguageMenu({
                     />
                     {lang.label}
                   </span>
-                  {isActive && <Check className="size-4 text-[var(--text-secondary)]" />}
+                  {isActive && <Check className="size-4 text-secondary" />}
                 </button>
               </li>
             );

package/src/shell.ts

@@ -12,7 +12,7 @@ export * from "./shell/top-bar-brand";
 export * from "./shell/auth-layout";
 // 0.31.0: the settings and admin pages' shell (docs/settings-harmonization.md §3, §5).
 export { SettingsLayout, SETTINGS_SEARCH_THRESHOLD } from "./settings/settings-layout";
-export type { SettingsLayoutProps, SettingsLayoutWidth } from "./settings/settings-layout";
+export type { SettingsLayoutProps, SettingsLayoutWidth, SettingsDocumentTitleParts } from "./settings/settings-layout";
 export {
   useSettingsRoute,
   resolveSettingsLocation,

package/src/testing/index.ts

@@ -11,3 +11,14 @@ export {
   undeclaredCssVariables,
   type UndeclaredCssVariablesOptions,
 } from "./css-variables";
+// 0.34 (refactor audit 2026-10, TST-10): the environment jsdom lacks — a `matchMedia`
+// that answers from a viewport width (right at every text size) and a `ResizeObserver`
+// the test drives. Framework-free: each returns its own undo.
+export {
+  stubResizeObserver,
+  stubViewportWidth,
+  viewportMatchMedia,
+  type ResizeObserverStub,
+  type StubbedBoxSize,
+  type ViewportOptions,
+} from "./viewport";

package/src/testing/viewport.ts

@@ -0,0 +1,251 @@
+/**
+ * Environment stubs for an app's own tests (0.34, refactor audit 2026-10, TST-10): the
+ * two browser APIs jsdom does not have and the kit's layout reads — `matchMedia` and
+ * `ResizeObserver`.
+ *
+ * Every suite rebuilt them by hand: the kit stubbed `matchMedia` in 25 files and defined
+ * the same `stubPhone()` eight times, keksdose stubs it in 41, and most copies answer
+ * one literal string. That breaks quietly at Large text, where `md` is 960 px and the
+ * phone query the kit writes is `(width < 960px)`, not `(width < 768px)`. These answer
+ * every width query from a WIDTH, as a browser does, so they stay right at every text
+ * size (docs/text-size-harmonization.md §3.3). The reference is keksdose's
+ * `frontend/src/test/viewport.ts`, which this generalises.
+ *
+ * Framework-free, like the rest of `@eifi1/ui-kit/testing`: nothing here imports vitest
+ * or jest. Each stub returns its own undo, so it works under either runner, and a suite
+ * that prefers `vi.stubGlobal` passes it {@link viewportMatchMedia} instead.
+ */
+
+/** The media features a test may want besides the width. Each is off by default. */
+export interface ViewportOptions {
+  /** The primary pointer is a finger: `(pointer: coarse)`, `(any-pointer: coarse)` and
+   *  `(hover: none)` match; `(pointer: fine)` and `(hover: hover)` do not. */
+  coarse?: boolean;
+  /** The person asked for less motion: `(prefers-reduced-motion: reduce)` matches, and
+   *  the kit's overlays skip their exit animations. */
+  reducedMotion?: boolean;
+  /** `(prefers-color-scheme: dark)` matches (`light` does not). */
+  dark?: boolean;
+  /** `(prefers-contrast: more)` matches. */
+  moreContrast?: boolean;
+}
+
+/** One length in CSS px. A media query's `rem`/`em` is the browser's default font size,
+ *  16 px, never `<html>`'s — the kit's own `breakpointQuery` writes px. */
+function lengthPx(value: string, unit: string): number {
+  return unit === "px" ? Number(value) : Number(value) * 16;
+}
+
+const RANGE = /^\(\s*width\s*(<=|>=|<|>)\s*([\d.]+)(px|r?em)\s*\)$/;
+const MIN_MAX = /^\(\s*(min|max)-width\s*:\s*([\d.]+)(px|r?em)\s*\)$/;
+const FEATURE = /^\(\s*([a-z-]+)\s*:\s*([a-z-]+)\s*\)$/;
+
+/** One `(…)` condition, or a media type. */
+function condition(part: string, width: number, options: ViewportOptions): boolean {
+  const q = part.trim();
+  if (q === "all" || q === "screen") return true;
+  const range = RANGE.exec(q);
+  if (range) {
+    const px = lengthPx(range[2], range[3]);
+    switch (range[1]) {
+      case "<":
+        return width < px;
+      case "<=":
+        return width <= px;
+      case ">":
+        return width > px;
+      default:
+        return width >= px;
+    }
+  }
+  const minMax = MIN_MAX.exec(q);
+  if (minMax) {
+    const px = lengthPx(minMax[2], minMax[3]);
+    return minMax[1] === "min" ? width >= px : width <= px;
+  }
+  const feature = FEATURE.exec(q);
+  if (!feature) return false;
+  const [, name, value] = feature;
+  const coarse = Boolean(options.coarse);
+  switch (name) {
+    case "pointer":
+    case "any-pointer":
+      return value === (coarse ? "coarse" : "fine");
+    case "hover":
+    case "any-hover":
+      return value === (coarse ? "none" : "hover");
+    case "prefers-reduced-motion":
+      return value === (options.reducedMotion ? "reduce" : "no-preference");
+    case "prefers-color-scheme":
+      return value === (options.dark ? "dark" : "light");
+    case "prefers-contrast":
+      return value === (options.moreContrast ? "more" : "no-preference");
+    default:
+      return false;
+  }
+}
+
+/**
+ * A `window.matchMedia` for a viewport `width` CSS px wide.
+ *
+ * Width queries answer from `width`: the range syntax the kit writes for `max-*`
+ * (`(width < 768px)`) and every other comparison, `(min-width: …)` and `(max-width: …)`,
+ * in px or rem; `and` and comma lists combine as in CSS. The features in `options` answer
+ * as set there; every other query is false. The lists it returns never change, so
+ * nothing fires `change`: a test that changes the width stubs again and renders again.
+ *
+ * Hand it to the runner's own global stub where the suite undoes stubs that way —
+ * `vi.stubGlobal("matchMedia", viewportMatchMedia(375))` — or use
+ * {@link stubViewportWidth}.
+ */
+export function viewportMatchMedia(
+  width: number,
+  options: ViewportOptions = {},
+): (query: string) => MediaQueryList {
+  const answer = (query: string) =>
+    query
+      .split(",")
+      .some((alternative) =>
+        alternative.split(/\s+and\s+/).every((part) => condition(part, width, options)),
+      );
+  return (query: string) =>
+    ({
+      matches: answer(query),
+      media: query,
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    }) as unknown as MediaQueryList;
+}
+
+/**
+ * Make `window.matchMedia` answer as a viewport `width` CSS px wide (see
+ * {@link viewportMatchMedia}), and return the undo: it puts back what was there, which
+ * in jsdom is nothing — no `matchMedia` at all, the desktop fallback of every kit hook.
+ *
+ * ```ts
+ * let undo = () => {};
+ * afterEach(() => undo());
+ * it("shows cards on a phone", () => {
+ *   undo = stubViewportWidth(375);
+ *   …
+ * });
+ * ```
+ *
+ * Right at every text size: at Large the kit's phone query is `(width < 960px)`, which a
+ * 375 px viewport matches and a 1280 px one does not, as in a browser.
+ */
+export function stubViewportWidth(width: number, options: ViewportOptions = {}): () => void {
+  const before = Object.getOwnPropertyDescriptor(window, "matchMedia");
+  Object.defineProperty(window, "matchMedia", {
+    configurable: true,
+    writable: true,
+    value: viewportMatchMedia(width, options),
+  });
+  return () => {
+    if (before) Object.defineProperty(window, "matchMedia", before);
+    else Reflect.deleteProperty(window, "matchMedia");
+  };
+}
+
+/** A box size for {@link ResizeObserverStub.resize}, in CSS px. */
+export interface StubbedBoxSize {
+  width: number;
+  height: number;
+}
+
+/** What {@link stubResizeObserver} returns: the test drives the observers. */
+export interface ResizeObserverStub {
+  /**
+   * Report `target` at `size` to every live observer watching it, as a browser does once
+   * layout settles: one entry, with `contentRect` and the three box sizes all `size`.
+   * Synchronous; wrap it in `act()` when the callback sets state.
+   */
+  resize(target: Element, size: StubbedBoxSize): void;
+  /** The elements some live observer watches now, each once. */
+  observed(): Element[];
+  /** Put back the `ResizeObserver` that was there before — in jsdom, none. */
+  restore(): void;
+}
+
+/**
+ * Install a `ResizeObserver` the test drives. jsdom has none, and lays nothing out, so a
+ * component that measures itself (a windowed list, a fitted chart, a measured grid)
+ * either crashes on the missing global or never learns a size. Observers here record
+ * what they watch and are called only by {@link ResizeObserverStub.resize}.
+ *
+ * ```ts
+ * const ro = stubResizeObserver();
+ * afterEach(() => ro.restore());
+ * act(() => ro.resize(screen.getByRole("list"), { width: 400, height: 320 }));
+ * ```
+ */
+export function stubResizeObserver(): ResizeObserverStub {
+  const live = new Set<StubResizeObserver>();
+
+  class StubResizeObserver {
+    readonly targets = new Set<Element>();
+    constructor(readonly callback: ResizeObserverCallback) {
+      live.add(this);
+    }
+    observe(target: Element) {
+      this.targets.add(target);
+    }
+    unobserve(target: Element) {
+      this.targets.delete(target);
+    }
+    disconnect() {
+      this.targets.clear();
+      live.delete(this);
+    }
+  }
+
+  const before = Object.getOwnPropertyDescriptor(globalThis, "ResizeObserver");
+  Object.defineProperty(globalThis, "ResizeObserver", {
+    configurable: true,
+    writable: true,
+    value: StubResizeObserver,
+  });
+
+  return {
+    resize(target, { width, height }) {
+      const box = [{ inlineSize: width, blockSize: height }];
+      const contentRect = {
+        x: 0,
+        y: 0,
+        top: 0,
+        left: 0,
+        width,
+        height,
+        right: width,
+        bottom: height,
+        toJSON: () => ({ x: 0, y: 0, width, height }),
+      };
+      const entry = {
+        target,
+        contentRect,
+        borderBoxSize: box,
+        contentBoxSize: box,
+        devicePixelContentBoxSize: box,
+      } as unknown as ResizeObserverEntry;
+      for (const observer of [...live]) {
+        if (observer.targets.has(target)) {
+          observer.callback([entry], observer as unknown as ResizeObserver);
+        }
+      }
+    },
+    observed() {
+      const all: Element[] = [];
+      for (const observer of live) for (const target of observer.targets) if (!all.includes(target)) all.push(target);
+      return all;
+    },
+    restore() {
+      live.clear();
+      if (before) Object.defineProperty(globalThis, "ResizeObserver", before);
+      else Reflect.deleteProperty(globalThis, "ResizeObserver");
+    },
+  };
+}

package/src/theme/color.ts

@@ -195,10 +195,16 @@ export function solveLightness(
   const bgL = rgbToOklch(against).l;
   let lo = direction === "darker" ? 0 : bgL;
   let hi = direction === "darker" ? bgL : 1;
+  // Measured on the HEX both colours are painted as, never on the float (round 0.34
+  // BUG-8): a solve that stopped on the float colour rounded to a hex just under the
+  // target — brand #000000's light income figure solved to 4.5000 and shipped at 4.49:1.
+  // Rounding keeps contrast monotonic in each half, so the bisection still holds, and
+  // the side it returns is the side whose hex clears the target.
+  const bg = toHex(against);
 
   for (let i = 0; i < 24; i++) {
     const mid = (lo + hi) / 2;
-    const got = contrast(oklchToRgb({ l: mid, c, h }), against);
+    const got = contrast(toHex(oklchToRgb({ l: mid, c, h })), bg);
     // Moving AWAY from the background raises contrast; which way that is depends on
     // whether we are going lighter or darker.
     if (got < target) {

package/src/theme/palette-derive.ts

@@ -187,8 +187,21 @@ const BORDER_CONTRAST = 1.5;
 /** The most tint a surface can carry before it stops reading as a neutral ground. */
 const MAX_SURFACE_CHROMA = 0.034;
 
-function surfaceSet(hue: number, mode: ThemeMode, tint: number) {
-  const c = MAX_SURFACE_CHROMA * Math.max(0, Math.min(1, tint));
+/**
+ * The brand chroma from which the surfaces and the greys carry the brand's hue in full;
+ * below it they carry it in proportion, down to none for a grey (round 0.34 BUG-8). A
+ * grey has no hue — OKLCH reports 0, which is pink — and at full tint #808080 painted
+ * every surface #eddde1.
+ */
+const FULL_HUE_CHROMA = 0.06;
+
+/** How much of the brand's hue the neutrals may carry: 0 for a grey, 1 from {@link FULL_HUE_CHROMA}. */
+function hueWeight(brand: Oklch): number {
+  return Math.min(1, brand.c / FULL_HUE_CHROMA);
+}
+
+function surfaceSet(hue: number, mode: ThemeMode, tint: number, weight: number) {
+  const c = MAX_SURFACE_CHROMA * Math.max(0, Math.min(1, tint)) * weight;
   const L = SURFACE_L[mode];
   const bgPage = oklchToHex({ l: L.page, c, h: hue });
   const bgSurface = oklchToHex({ l: L.surface, c, h: hue });
@@ -263,7 +276,8 @@ export function derivePalette({
   const targets = { primary: 10, secondary: 7, muted: 4.6, ...textContrast };
 
   // ── Surfaces, from the brand's hue.
-  const surfaces = surfaceSet(brand.h, mode, surfaceTint);
+  const weight = hueWeight(brand);
+  const surfaces = surfaceSet(brand.h, mode, surfaceTint, weight);
   // Every text role is solved against the WORST of the three, so a token is legible
   // wherever it lands. Solving against `bgSurface` alone is the mistake that makes a
   // muted label fail on the page background it also sits on.
@@ -275,7 +289,7 @@ export function derivePalette({
   );
 
   // ── Text. A trace of the brand hue keeps the greys from reading cold on a warm page.
-  const textChroma = 0.014;
+  const textChroma = 0.014 * weight;
   const textPrimary = solveAgainst(brand.h, textChroma, targets.primary, worstSurface, mode);
   const textSecondary = solveAgainst(brand.h, textChroma, targets.secondary, worstSurface, mode);
   const textMuted = solveAgainst(brand.h, textChroma, targets.muted, worstSurface, mode);
@@ -479,10 +493,11 @@ export function derivePalette({
   // "No money has moved": a quiet grey at a fixed lightness, but printed as TEXT (the
   // numpad's sign, a future row's figure), so it gets the text floor too (0.33). The
   // fixed lightness left it at 4.24:1 on four light pages.
-  const neutralFloor = solveLightness(4.5, parseHex(worstText)!, brand.h, 0.012, mode === "light" ? "darker" : "lighter");
+  const neutralChroma = 0.012 * weight;
+  const neutralFloor = solveLightness(4.5, parseHex(worstText)!, brand.h, neutralChroma, mode === "light" ? "darker" : "lighter");
   const moneyNeutral = oklchToHex({
     l: mode === "light" ? Math.min(0.52, neutralFloor) : Math.max(0.72, neutralFloor),
-    c: 0.012,
+    c: neutralChroma,
     h: brand.h,
   });
 
@@ -561,9 +576,16 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
   // `--brand-muted`, `--brand-bg` and `--brand-bg-hover`, mixed as tokens.css mixes them.
   const { brandMuted, brandBg, brandBgHover } = brandSoft(t);
 
+  // The 0.05 of slack is for a pair with a color-mix on one side, and only for that: the
+  // browser mixes in float and paints the result, where this mixes and rounds to hex, so
+  // the two can differ by a hair. Hex against hex is what the page paints, measured
+  // exactly — the slack used to cover those too, and passed the Contrast preset's dark
+  // brand fill at 2.998:1 (round 0.34 BUG-8).
+  const MIXED = /\b(bgHover|brandMuted|brandBg|brandBgHover)\b/;
   const add = (pair: string, fg: string, bg: string, required: number, rule: string) => {
     const ratio = contrast(fg, bg);
-    checks.push({ pair, ratio, required, rule, passes: ratio >= required - 0.05 });
+    const slack = MIXED.test(pair) ? 0.05 : 0;
+    checks.push({ pair, ratio, required, rule, passes: ratio >= required - slack });
   };
 
   for (const [name, bg] of surfaces) {