@eifi1/ui-kit 0.32.1 → 0.33.0

package/src/testing/css-variables.generated.ts

@@ -0,0 +1,112 @@
+// GENERATED by scripts/gen-kit-css-variables.mjs — do not edit by hand. Re-run it after
+// changing tokens.css or upgrading Tailwind; src/__tests__/token-vars-declared.test.ts
+// fails while this is stale.
+
+/** Every custom property tokens.css declares, `@theme inline` names and `--app-nav-h`
+ *  left out (100 names). */
+export const KIT_NAMES =
+  "--bg-active --bg-hover --bg-inverse --bg-page --bg-surface --bg-surface-2 --border " +
+  "--border-strong --brand --brand-bg --brand-bg-hover --brand-contrast --brand-hover --brand-muted " +
+  "--breakpoint-3xl --chart-1 --chart-2 --chart-3 --chart-4 --chart-5 --chart-6 --chart-7 --chart-8 " +
+  "--chart-9 --danger --danger-bg --danger-border --danger-border-strong --danger-contrast " +
+  "--danger-hover --flyout-from --focus-ring-width --hue-blue --hue-blue-bg --hue-blue-border " +
+  "--hue-blue-contrast --hue-indigo --hue-indigo-bg --hue-indigo-border --hue-indigo-contrast " +
+  "--hue-orange --hue-orange-bg --hue-orange-border --hue-orange-contrast --hue-purple " +
+  "--hue-purple-bg --hue-purple-border --hue-purple-contrast --hue-teal --hue-teal-bg " +
+  "--hue-teal-border --hue-teal-contrast --info --info-bg --info-border --info-contrast --media-ink " +
+  "--media-scrim --media-scrim-hover --money-expense --money-expense-contrast --money-income " +
+  "--money-income-contrast --money-net --money-net-contrast --money-neutral " +
+  "--money-neutral-contrast --neutral --neutral-contrast --status-edited --status-error " +
+  "--status-pending --status-synced --success --success-bg --success-border --success-contrast " +
+  "--text-caption --text-inverse --text-micro --text-muted --text-placeholder --text-primary " +
+  "--text-secondary --toast-action-bg --toast-action-fg --toast-danger-bg --toast-danger-border " +
+  "--toast-info-bg --toast-info-border --toast-success-bg --toast-success-border --toast-warning-bg " +
+  "--toast-warning-border --warning --warning-bg --warning-border --warning-border-strong " +
+  "--warning-contrast --z-toast";
+
+/** The theme variables of Tailwind 4.3.3's `theme.css` (413 names). */
+export const TAILWIND_THEME_NAMES =
+  "--animate-bounce --animate-ping --animate-pulse --animate-spin --aspect-video --blur-2xl " +
+  "--blur-3xl --blur-lg --blur-md --blur-sm --blur-xl --blur-xs --breakpoint-2xl --breakpoint-lg " +
+  "--breakpoint-md --breakpoint-sm --breakpoint-xl --color-amber-100 --color-amber-200 " +
+  "--color-amber-300 --color-amber-400 --color-amber-50 --color-amber-500 --color-amber-600 " +
+  "--color-amber-700 --color-amber-800 --color-amber-900 --color-amber-950 --color-black " +
+  "--color-blue-100 --color-blue-200 --color-blue-300 --color-blue-400 --color-blue-50 " +
+  "--color-blue-500 --color-blue-600 --color-blue-700 --color-blue-800 --color-blue-900 " +
+  "--color-blue-950 --color-cyan-100 --color-cyan-200 --color-cyan-300 --color-cyan-400 " +
+  "--color-cyan-50 --color-cyan-500 --color-cyan-600 --color-cyan-700 --color-cyan-800 " +
+  "--color-cyan-900 --color-cyan-950 --color-emerald-100 --color-emerald-200 --color-emerald-300 " +
+  "--color-emerald-400 --color-emerald-50 --color-emerald-500 --color-emerald-600 " +
+  "--color-emerald-700 --color-emerald-800 --color-emerald-900 --color-emerald-950 " +
+  "--color-fuchsia-100 --color-fuchsia-200 --color-fuchsia-300 --color-fuchsia-400 " +
+  "--color-fuchsia-50 --color-fuchsia-500 --color-fuchsia-600 --color-fuchsia-700 " +
+  "--color-fuchsia-800 --color-fuchsia-900 --color-fuchsia-950 --color-gray-100 --color-gray-200 " +
+  "--color-gray-300 --color-gray-400 --color-gray-50 --color-gray-500 --color-gray-600 " +
+  "--color-gray-700 --color-gray-800 --color-gray-900 --color-gray-950 --color-green-100 " +
+  "--color-green-200 --color-green-300 --color-green-400 --color-green-50 --color-green-500 " +
+  "--color-green-600 --color-green-700 --color-green-800 --color-green-900 --color-green-950 " +
+  "--color-indigo-100 --color-indigo-200 --color-indigo-300 --color-indigo-400 --color-indigo-50 " +
+  "--color-indigo-500 --color-indigo-600 --color-indigo-700 --color-indigo-800 --color-indigo-900 " +
+  "--color-indigo-950 --color-lime-100 --color-lime-200 --color-lime-300 --color-lime-400 " +
+  "--color-lime-50 --color-lime-500 --color-lime-600 --color-lime-700 --color-lime-800 " +
+  "--color-lime-900 --color-lime-950 --color-mauve-100 --color-mauve-200 --color-mauve-300 " +
+  "--color-mauve-400 --color-mauve-50 --color-mauve-500 --color-mauve-600 --color-mauve-700 " +
+  "--color-mauve-800 --color-mauve-900 --color-mauve-950 --color-mist-100 --color-mist-200 " +
+  "--color-mist-300 --color-mist-400 --color-mist-50 --color-mist-500 --color-mist-600 " +
+  "--color-mist-700 --color-mist-800 --color-mist-900 --color-mist-950 --color-neutral-100 " +
+  "--color-neutral-200 --color-neutral-300 --color-neutral-400 --color-neutral-50 " +
+  "--color-neutral-500 --color-neutral-600 --color-neutral-700 --color-neutral-800 " +
+  "--color-neutral-900 --color-neutral-950 --color-olive-100 --color-olive-200 --color-olive-300 " +
+  "--color-olive-400 --color-olive-50 --color-olive-500 --color-olive-600 --color-olive-700 " +
+  "--color-olive-800 --color-olive-900 --color-olive-950 --color-orange-100 --color-orange-200 " +
+  "--color-orange-300 --color-orange-400 --color-orange-50 --color-orange-500 --color-orange-600 " +
+  "--color-orange-700 --color-orange-800 --color-orange-900 --color-orange-950 --color-pink-100 " +
+  "--color-pink-200 --color-pink-300 --color-pink-400 --color-pink-50 --color-pink-500 " +
+  "--color-pink-600 --color-pink-700 --color-pink-800 --color-pink-900 --color-pink-950 " +
+  "--color-purple-100 --color-purple-200 --color-purple-300 --color-purple-400 --color-purple-50 " +
+  "--color-purple-500 --color-purple-600 --color-purple-700 --color-purple-800 --color-purple-900 " +
+  "--color-purple-950 --color-red-100 --color-red-200 --color-red-300 --color-red-400 " +
+  "--color-red-50 --color-red-500 --color-red-600 --color-red-700 --color-red-800 --color-red-900 " +
+  "--color-red-950 --color-rose-100 --color-rose-200 --color-rose-300 --color-rose-400 " +
+  "--color-rose-50 --color-rose-500 --color-rose-600 --color-rose-700 --color-rose-800 " +
+  "--color-rose-900 --color-rose-950 --color-sky-100 --color-sky-200 --color-sky-300 " +
+  "--color-sky-400 --color-sky-50 --color-sky-500 --color-sky-600 --color-sky-700 --color-sky-800 " +
+  "--color-sky-900 --color-sky-950 --color-slate-100 --color-slate-200 --color-slate-300 " +
+  "--color-slate-400 --color-slate-50 --color-slate-500 --color-slate-600 --color-slate-700 " +
+  "--color-slate-800 --color-slate-900 --color-slate-950 --color-stone-100 --color-stone-200 " +
+  "--color-stone-300 --color-stone-400 --color-stone-50 --color-stone-500 --color-stone-600 " +
+  "--color-stone-700 --color-stone-800 --color-stone-900 --color-stone-950 --color-taupe-100 " +
+  "--color-taupe-200 --color-taupe-300 --color-taupe-400 --color-taupe-50 --color-taupe-500 " +
+  "--color-taupe-600 --color-taupe-700 --color-taupe-800 --color-taupe-900 --color-taupe-950 " +
+  "--color-teal-100 --color-teal-200 --color-teal-300 --color-teal-400 --color-teal-50 " +
+  "--color-teal-500 --color-teal-600 --color-teal-700 --color-teal-800 --color-teal-900 " +
+  "--color-teal-950 --color-violet-100 --color-violet-200 --color-violet-300 --color-violet-400 " +
+  "--color-violet-50 --color-violet-500 --color-violet-600 --color-violet-700 --color-violet-800 " +
+  "--color-violet-900 --color-violet-950 --color-white --color-yellow-100 --color-yellow-200 " +
+  "--color-yellow-300 --color-yellow-400 --color-yellow-50 --color-yellow-500 --color-yellow-600 " +
+  "--color-yellow-700 --color-yellow-800 --color-yellow-900 --color-yellow-950 --color-zinc-100 " +
+  "--color-zinc-200 --color-zinc-300 --color-zinc-400 --color-zinc-50 --color-zinc-500 " +
+  "--color-zinc-600 --color-zinc-700 --color-zinc-800 --color-zinc-900 --color-zinc-950 " +
+  "--container-2xl --container-2xs --container-3xl --container-3xs --container-4xl --container-5xl " +
+  "--container-6xl --container-7xl --container-lg --container-md --container-sm --container-xl " +
+  "--container-xs --default-font-family --default-font-feature-settings " +
+  "--default-font-variation-settings --default-mono-font-family " +
+  "--default-mono-font-feature-settings --default-mono-font-variation-settings " +
+  "--default-transition-duration --default-transition-timing-function --drop-shadow-2xl " +
+  "--drop-shadow-lg --drop-shadow-md --drop-shadow-sm --drop-shadow-xl --drop-shadow-xs --ease-in " +
+  "--ease-in-out --ease-out --font-mono --font-sans --font-serif --font-weight-black " +
+  "--font-weight-bold --font-weight-extrabold --font-weight-extralight --font-weight-light " +
+  "--font-weight-medium --font-weight-normal --font-weight-semibold --font-weight-thin " +
+  "--inset-shadow-2xs --inset-shadow-sm --inset-shadow-xs --leading-loose --leading-normal " +
+  "--leading-relaxed --leading-snug --leading-tight --perspective-distant --perspective-dramatic " +
+  "--perspective-midrange --perspective-near --perspective-normal --radius-2xl --radius-3xl " +
+  "--radius-4xl --radius-lg --radius-md --radius-sm --radius-xl --radius-xs --shadow-2xl " +
+  "--shadow-2xs --shadow-lg --shadow-md --shadow-sm --shadow-xl --shadow-xs --spacing --text-2xl " +
+  "--text-2xl--line-height --text-3xl --text-3xl--line-height --text-4xl --text-4xl--line-height " +
+  "--text-5xl --text-5xl--line-height --text-6xl --text-6xl--line-height --text-7xl " +
+  "--text-7xl--line-height --text-8xl --text-8xl--line-height --text-9xl --text-9xl--line-height " +
+  "--text-base --text-base--line-height --text-lg --text-lg--line-height --text-shadow-2xs " +
+  "--text-shadow-lg --text-shadow-md --text-shadow-sm --text-shadow-xs --text-sm " +
+  "--text-sm--line-height --text-xl --text-xl--line-height --text-xs --text-xs--line-height " +
+  "--tracking-normal --tracking-tight --tracking-tighter --tracking-wide --tracking-wider " +
+  "--tracking-widest";

package/src/testing/css-variables.ts

@@ -0,0 +1,191 @@
+import { KIT_NAMES, TAILWIND_THEME_NAMES } from "./css-variables.generated";
+
+/**
+ * The guard against an undeclared CSS custom property (0.33,
+ * docs/colour-roles-harmonization.md §8, §12.5).
+ *
+ * A `var(--name)` with no fallback, where nothing declares `--name`, makes the whole
+ * declaration invalid at computed-value time: `fill` inherits, `color` inherits, a
+ * background goes transparent. Kurvenschmiede's control diagram painted
+ * `fill-[var(--surface)]` — a token that never existed (the kit's is `--bg-surface`) —
+ * and drew black boxes on a public page. The class compiled, the build passed, the type
+ * checker had no opinion, and nothing in any suite noticed. This is the check that
+ * notices, run from an app's own test over the source texts the app collects.
+ *
+ * Browser-safe on purpose, like the rest of the kit: it takes TEXTS, not paths, so an app
+ * reads its files however its setup allows (`import.meta.glob` with `?raw`, or `node:fs`)
+ * and the kit carries no `node:fs`.
+ */
+
+/** Every custom property the installed kit declares or publishes to apps.
+ *
+ *  Generated from `tokens.css` when the kit is built (scripts/gen-kit-css-variables.mjs),
+ *  so it is always the installed version's, and an app never searches `node_modules`.
+ *  It leaves out two kinds of name on purpose:
+ *  - a name declared only in an `@theme inline` block (`--text-color-muted`,
+ *    `--background-color-surface`): Tailwind emits no variable for it, so
+ *    `var(--text-color-muted)` would pass a guard that counted it and paint nothing;
+ *  - AppShell's measured `--app-nav-h`, which exists only while an AppShell is mounted —
+ *    on a landing, legal, sign-in or pay page it is undefined. Read it with a fallback,
+ *    `var(--app-nav-h,0px)`, as every kit read does.
+ *  Everything `applyTokenSet` and More contrast write on `<html>` is in, through the
+ *  stylesheet's `:root` / `.dark` mirror. Component internals (`--slider-fill`, `--fp-*`,
+ *  `--icon-button-tone`, `--label-strip-edge`) are not: an app that reads one depends on
+ *  the kit's internals, and the guard says so. */
+export const KIT_CSS_VARIABLES: ReadonlySet<string> = new Set(KIT_NAMES.split(" "));
+
+/** Tailwind's own theme variables (`--color-rose-500`, `--spacing`, `--text-sm` …), from
+ *  the `tailwindcss/theme.css` the kit builds with. Tailwind emits one when a scanned file
+ *  names it, so a `var()` of it resolves. */
+const TAILWIND_THEME: ReadonlySet<string> = new Set(TAILWIND_THEME_NAMES.split(" "));
+
+/** A Tailwind PALETTE colour: a hue with a shade, black or white. `refusePalette` reports
+ *  these although they resolve — an app that has no palette lint asks this test to be
+ *  its refusal. */
+const PALETTE_VARIABLE = /^--color-(?:[a-z]+-\d{2,3}|black|white)$/;
+
+/** Read only where it is set: the guard accepts it in a fallback use, never bare. */
+const APP_NAV_H = "--app-nav-h";
+
+export interface UndeclaredCssVariablesOptions {
+  /** Variables a library writes at runtime, as names or patterns:
+   *  `["--radix-collapsible-content-height"]`. An app's own writes are found in its
+   *  source and need no listing. */
+  runtime?: readonly (string | RegExp)[];
+  /** Also check `var(--x, …)`. Off by default: a fallback says what happens when the
+   *  name is missing. `--app-nav-h` counts as declared only here. */
+  checkFallbacks?: boolean;
+  /** Report Tailwind palette variables (`--color-red-500`, `--color-white`) although
+   *  they resolve. Default false. */
+  refusePalette?: boolean;
+}
+
+/** Comments are not CSS. `/* *\/` in both; `//` in TS only (not after a `:`, so a URL in a
+ *  string survives). Replaced by spaces of the same shape, so line numbers hold. */
+function stripComments(text: string, isCss: boolean): string {
+  const blank = (m: string) => m.replace(/[^\n]/g, " ");
+  const noBlocks = text.replace(/\/\*[\s\S]*?\*\//g, blank);
+  return isCss ? noBlocks : noBlocks.replace(/(^|[^:])(\/\/[^\n]*)/g, (_, pre: string, c: string) => pre + blank(c));
+}
+
+/** The text with every `@theme … inline … { … }` block blanked out, braces and all. */
+function withoutInlineTheme(css: string): string {
+  let out = css;
+  for (const m of css.matchAll(/@theme\b[^{;]*\binline\b[^{;]*\{/g)) {
+    let depth = 0;
+    let end = m.index + m[0].length - 1;
+    for (; end < css.length; end++) {
+      if (css[end] === "{") depth++;
+      else if (css[end] === "}" && --depth === 0) break;
+    }
+    out = out.slice(0, m.index) + css.slice(m.index, end + 1).replace(/[^\n]/g, " ") + out.slice(end + 1);
+  }
+  return out;
+}
+
+/**
+ * Every custom property a stylesheet declares (`--name:`), in any block — except a name
+ * declared only inside `@theme inline`, which Tailwind never emits as a variable. Comments
+ * are skipped. The same rule builds {@link KIT_CSS_VARIABLES} from `tokens.css`.
+ */
+export function declaredCustomProperties(css: string): Set<string> {
+  const code = withoutInlineTheme(stripComments(css, true));
+  return new Set([...code.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)].map((m) => m[1]));
+}
+
+/** What an app's source writes at runtime: `setProperty("--name"`, a React style key
+ *  `"--name":`, a Tailwind arbitrary property `[--name:…]`. */
+function runtimeWrites(code: string): string[] {
+  return [
+    ...code.matchAll(/setProperty\(\s*["'`](--[a-zA-Z0-9_-]+)["'`]/g),
+    ...code.matchAll(/["'](--[a-zA-Z0-9_-]+)["']\s*:/g),
+    ...code.matchAll(/\[(--[a-zA-Z0-9_-]+):/g),
+  ].map((m) => m[1]);
+}
+
+/** A chart series' colour (`var(--color-total)`) is declared in a file with a `total: {`
+ *  config entry: the kit's ChartContainer writes `--color-<key>` for each key. */
+function chartKeys(code: string): Set<string> {
+  return new Set([...code.matchAll(/(?:^|[\s{,])["']?([A-Za-z_][\w-]*)["']?\s*:\s*\{/g)].map((m) => m[1]));
+}
+
+const isCssPath = (path: string) => /\.css(?:\?|$)/.test(path);
+
+/**
+ * Every `var(--name)` without a fallback that nothing declares, as `"path:line --name"`.
+ *
+ * `sources` maps a path to its text: the app's `.ts`, `.tsx` and `.css` source, tests
+ * left out. A name counts as declared when it is:
+ * 1. the kit's ({@link KIT_CSS_VARIABLES});
+ * 2. declared in any `.css` entry of `sources` (outside `@theme inline`);
+ * 3. written by the source at runtime (`setProperty`, a style key, `[--name:…]`);
+ * 4. one of Tailwind's theme variables — unless `refusePalette` and it is a palette colour;
+ * 5. a chart series' `--color-<key>`, in a file with a `<key>: {` entry;
+ * 6. listed in `options.runtime`.
+ *
+ * Not counted: comments; a use with a fallback, unless `checkFallbacks`; a name built at
+ * runtime (`` `var(--chart-${n})` `` — a name must be followed by `)` or `,`).
+ *
+ * It REFUSES A VACUOUS RUN: it throws when `sources` holds fewer than ten files, or when
+ * a `.css` entry is empty. Vitest stubs every stylesheet with an empty string by default,
+ * `?raw` included, so an app that reads its CSS that way without opting it out of the stub
+ * (`test.css.include`) would otherwise lose every declaration and every use in it, and
+ * this would pass or fail for the wrong reason.
+ */
+export function undeclaredCssVariables(
+  sources: Record<string, string>,
+  options: UndeclaredCssVariablesOptions = {},
+): string[] {
+  const { runtime = [], checkFallbacks = false, refusePalette = false } = options;
+  const entries = Object.entries(sources);
+  if (entries.length < 10) {
+    throw new Error(
+      `undeclaredCssVariables: only ${entries.length} source file(s) — the glob or the file list found ` +
+        `(almost) nothing, and a check over nothing passes. Pass the app's .ts/.tsx/.css source.`,
+    );
+  }
+  const emptyCss = entries.filter(([path, text]) => isCssPath(path) && text.trim() === "").map(([path]) => path);
+  if (emptyCss.length) {
+    throw new Error(
+      `undeclaredCssVariables: ${emptyCss.join(", ")} read as empty. Vitest stubs stylesheets with "" ` +
+        `(\`?raw\` too) unless the file is listed in \`test.css.include\`.`,
+    );
+  }
+
+  const code = entries.map(([path, text]) => [path, stripComments(text, isCssPath(path))] as const);
+  const declared = new Set<string>();
+  for (const [path, text] of code) {
+    if (isCssPath(path)) for (const name of declaredCustomProperties(text)) declared.add(name);
+    for (const name of runtimeWrites(text)) declared.add(name);
+  }
+  const listed = (name: string) =>
+    runtime.some((r) => (typeof r === "string" ? r === name : r.test(name)));
+
+  const out: string[] = [];
+  for (const [path, text] of code) {
+    let keys: Set<string> | null = null;
+    for (const m of text.matchAll(/var\(\s*(--[a-zA-Z0-9_-]+)\s*([,)])/g)) {
+      const [, name, next] = m;
+      const fallback = next === ",";
+      if (fallback && !checkFallbacks) continue;
+      if (KIT_CSS_VARIABLES.has(name) || declared.has(name) || listed(name)) continue;
+      if (fallback && name === APP_NAV_H) continue;
+      if (TAILWIND_THEME.has(name)) {
+        if (refusePalette && PALETTE_VARIABLE.test(name)) {
+          out.push(`${path}:${lineOf(text, m.index)} ${name} (a Tailwind palette colour; refusePalette is on)`);
+        }
+        continue;
+      }
+      const chart = /^--color-([A-Za-z_][\w-]*)$/.exec(name);
+      if (chart && (keys ??= chartKeys(text)).has(chart[1])) continue;
+      out.push(`${path}:${lineOf(text, m.index)} ${name}`);
+    }
+  }
+  return out;
+}
+
+function lineOf(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+}

package/src/testing/index.ts

@@ -0,0 +1,13 @@
+// `@eifi1/ui-kit/testing` — helpers an app runs from its OWN test suite (0.33).
+//
+// Not part of the main barrel: nothing here renders, and an app's production bundle has
+// no business carrying it. Browser-safe like the rest of the kit (no `node:fs`): each
+// helper takes texts, so an app collects them with `import.meta.glob` or `node:fs`, as
+// its setup allows. The first content is the guard against undeclared CSS custom
+// properties (docs/colour-roles-harmonization.md §8).
+export {
+  KIT_CSS_VARIABLES,
+  declaredCustomProperties,
+  undeclaredCssVariables,
+  type UndeclaredCssVariablesOptions,
+} from "./css-variables";

package/src/theme/contrast-tokens.ts

@@ -49,8 +49,9 @@ function toLab(hex: string): Lab | null {
 
 /** `color-mix(in oklab, a p, b)` as a hex — the same formula tokens.css's derived roles
  *  use, so a stepped value sits where the stylesheet would have put it. A colour that is
- *  not hex (a consumer's own token set) comes back unmixed. */
-function mix(a: string, b: string, p: number): string {
+ *  not hex (a consumer's own token set) comes back unmixed. The deriver mixes with it
+ *  too (`--bg-hover`, `--brand-muted`, `--brand-bg`, `--brand-bg-hover`). */
+export function mix(a: string, b: string, p: number): string {
   const A = toLab(a);
   const B = toLab(b);
   if (!A || !B) return a;
@@ -62,6 +63,56 @@ function mix(a: string, b: string, p: number): string {
   return toHex(oklchToRgb({ l, c, h }));
 }
 
+/**
+ * `--bg-hover` in tokens.css: this share of `--text-primary` mixed into `--bg-surface`.
+ *
+ * 5.5 %, down from 7 % in 0.33 (docs/colour-roles-harmonization.md §12.10): a hovered row
+ * on a card is the darkest fill (in dark, the lightest) that text sits on, and at 7 % the
+ * light status colours, the money colours and Ink/Moss/Plum's muted text fell to
+ * 4.25–4.49:1 on it. The status literals are fixed, the same in every preset, so the
+ * hover moved instead: text wins over the hover's step. At 5.5 % the step from the card
+ * is still 1.09–1.13:1, above the 1.08:1 the kit's hover rule asks (§12.2). The deriver
+ * solves the money colours against this fill, and tokens-css-audit.test.ts measures
+ * every text role on it in every shipped preset, so the two cannot part.
+ */
+export const HOVER_INK = 0.055;
+
+/** The card's hover fill (`--bg-hover`) for `t`, as tokens.css mixes it. */
+export function hoverFill(t: Pick<TokenSet, "textPrimary" | "bgSurface">): string {
+  return mix(t.textPrimary, t.bgSurface, HOVER_INK);
+}
+
+/**
+ * `--brand-muted` in tokens.css: this share of `--brand` mixed into `--text-primary`.
+ *
+ * 62 %, down from 70 % in 0.33 (docs/colour-roles-harmonization.md §12.11): the brand as
+ * text sits on its soft chip HOVERED too (`--brand-bg-hover` — ButtonGroupLink's current
+ * page, a selected day), and at 70 % it read 4.08–4.42:1 there in Default and Moss light
+ * and in Ink, Moss, Plum and Contrast dark. The brand could not move instead: the dark
+ * brands would have flipped their white label to the dark ink. Nor could the chip's hover
+ * lighten: by the time the text cleared 4.5:1 the hover sat 1.00:1 from the chip it
+ * hovers. So the text moves toward the ink, as `--bg-hover` moved for its text.
+ */
+export const BRAND_MUTED_SHARE = 0.62;
+/** `--brand-bg` and `--brand-bg-hover` in tokens.css: these shares of `--brand` mixed
+ *  into `--bg-surface`. */
+export const BRAND_BG_SHARE = 0.14;
+export const BRAND_BG_HOVER_SHARE = 0.24;
+
+/** `--brand-muted`, `--brand-bg` and `--brand-bg-hover` for `t`, as tokens.css mixes them.
+ *  tokens-css-audit.test.ts holds the three shares equal to the stylesheet's. */
+export function brandSoft(t: Pick<TokenSet, "brand" | "textPrimary" | "bgSurface">): {
+  brandMuted: string;
+  brandBg: string;
+  brandBgHover: string;
+} {
+  return {
+    brandMuted: mix(t.brand, t.textPrimary, BRAND_MUTED_SHARE),
+    brandBg: mix(t.brand, t.bgSurface, BRAND_BG_SHARE),
+    brandBgHover: mix(t.brand, t.bgSurface, BRAND_BG_HOVER_SHARE),
+  };
+}
+
 /** WCAG 1.4.11 for a component's boundary. */
 const BORDER_TARGET = 3;
 /** `--border-strong` in tokens.css: 55 % border, 45 % text. */

package/src/theme/palette-derive.ts

@@ -13,6 +13,7 @@ import {
   solveLightness,
 } from "./color";
 import type { CvdType, Oklch } from "./color";
+import { brandSoft, hoverFill } from "./contrast-tokens";
 
 /**
  * Build a whole palette from one brand colour, plus any number of colours pinned by
@@ -161,7 +162,14 @@ function placeHue(home: number, slack: number, taken: number[]): number {
 const SURFACE_L = {
   // Light: the PAGE is slightly darker than the cards on it, so a card reads as raised
   // without needing a shadow to say so. Matches the shipped presets' relationship.
-  light: { page: 0.912, surface: 0.945, surface2: 0.929 },
+  //
+  // The light WELL is the page itself (0.33, docs/colour-roles-harmonization.md §5.3,
+  // k26). Between the card and the page it sat 1.02–1.05:1 from the card it is inset
+  // in, which is no well at all; at the page's lightness it stands out from the card
+  // exactly as far as the card does from the page, and nothing re-solves, because the
+  // page is already the surface every text role is solved against. Dark keeps its
+  // well a step lighter than the card (1.11–1.13:1).
+  light: { page: 0.912, surface: 0.945, surface2: 0.912 },
   dark: { page: 0.158, surface: 0.206, surface2: 0.249 },
 } as const;
 
@@ -272,6 +280,19 @@ export function derivePalette({
   const textSecondary = solveAgainst(brand.h, textChroma, targets.secondary, worstSurface, mode);
   const textMuted = solveAgainst(brand.h, textChroma, targets.muted, worstSurface, mode);
 
+  // The darkest fill text sits on (the lightest, in dark): the worst surface, or a
+  // hovered row on the card (`--bg-hover`), which in light is a shade darker than the
+  // page. The colours that are solved exactly to 4.5:1 — money, the semantic text — are
+  // solved against this, so they hold on a hovered row too (0.33, §12.10). The text
+  // roles above keep their margin (4.6:1 and up) and need no second solve.
+  const hover = hoverFill({ textPrimary, bgSurface: surfaces.bgSurface });
+  const worstText = [worstSurface, hover].reduce((a, b) =>
+    contrast(a, mode === "light" ? "#000000" : "#ffffff") <
+    contrast(b, mode === "light" ? "#000000" : "#ffffff")
+      ? a
+      : b,
+  );
+
   // ── Brand. Keep the hue the caller asked for; move only the lightness, and only as
   // far as 3:1 against the worst surface — WCAG 1.4.11, since a brand-filled control is
   // a graphical object whose boundary has to be perceivable.
@@ -280,7 +301,7 @@ export function derivePalette({
   // NORMALISED, never the caller's raw string. `parseHex` accepts "4f46e5" and "#abc",
   // and passing either through unchanged put a value in the TokenSet that is not a CSS
   // colour — it then fails silently at paint time, three layers from here.
-  const brandHex =
+  let brandHex =
     brandRatio >= 3
       ? toHex(parseHex(anchors.brand)!)
       : solveAgainst(brand.h, brandChroma, 3, worstSurface, mode);
@@ -291,13 +312,39 @@ export function derivePalette({
         `${brandHex}; hue and chroma are unchanged.`,
     );
   }
+  // `--brand-muted` is the brand AS TEXT — a soft brand chip's label, an outline chip, a
+  // current link — and tokens.css derives it: 62 % brand into the ink. A brand solved
+  // to 3:1 left it at 4.43–4.51:1 in three dark presets (0.33, §5.5), so it gets the
+  // text floor here: the brand moves away from the surfaces, a step at a time, until its
+  // muted form clears 4.5:1 on the worst fill and on its own soft chip, at rest
+  // (`--brand-bg`) and hovered (`--brand-bg-hover`, the harder of the two: §12.11).
+  const brandMutedWorst = (hex: string) => {
+    const soft = brandSoft({ brand: hex, textPrimary, bgSurface: surfaces.bgSurface });
+    return Math.min(
+      contrast(soft.brandMuted, worstText),
+      contrast(soft.brandMuted, soft.brandBg),
+      contrast(soft.brandMuted, soft.brandBgHover),
+    );
+  };
+  for (let i = 0; i < 40 && brandMutedWorst(brandHex) < 4.5; i++) {
+    const lch = hexToOklch(brandHex)!;
+    brandHex = oklchToHex({ ...lch, l: mode === "light" ? lch.l - 0.005 : lch.l + 0.005 });
+  }
+  if (brandMutedWorst(brandHex) < 4.5) {
+    warnings.push(
+      `the brand as text (--brand-muted) reaches only ${brandMutedWorst(brandHex).toFixed(2)}:1 ` +
+        `against the ${mode} surfaces (needs 4.5:1).`,
+    );
+  }
   const brandLch = hexToOklch(brandHex)!;
+  const brandContrast = contrastOn(brandHex);
   const brandHover = oklchToHex({
     ...brandLch,
-    // Hover moves AWAY from the page in both themes: darker on light, lighter on dark.
-    l: mode === "light" ? brandLch.l - 0.06 : brandLch.l + 0.06,
+    // Hover moves AWAY from the colour of the text on it (0.33, §5.5): darker under
+    // white, lighter under a dark ink. It used to move away from the page, which in dark
+    // lightened a fill that carries WHITE text, toward its own label: 4.07:1.
+    l: brandContrast === "#ffffff" ? brandLch.l - 0.06 : brandLch.l + 0.06,
   });
-  const brandContrast = contrastOn(brandHex);
   const onBrand = contrast(brandHex, brandContrast);
   if (onBrand < 4.5) {
     warnings.push(
@@ -352,7 +399,7 @@ export function derivePalette({
     const bg = tintOn(hue, chroma, surfaces.bgSurface, mode);
     const onSurface = solveLightness(
       4.5,
-      parseHex(worstSurface)!,
+      parseHex(worstText)!,
       hue,
       chroma,
       mode === "light" ? "darker" : "lighter",
@@ -425,11 +472,19 @@ export function derivePalette({
   // red/green pair — which is why the shipped presets use teal/amber/violet. Derived
   // here at fixed hues rather than from the brand, for the same reason `--danger` is:
   // a consumer who rebrands does not thereby change what "money out" looks like.
-  const money = (hue: number, target: number) => solveAgainst(hue, 0.12, target, worstSurface, mode);
+  const money = (hue: number, target: number) => solveAgainst(hue, 0.12, target, worstText, mode);
   const moneyIncome = money(175, 4.5);
   const moneyExpense = money(70, 4.5);
   const moneyNet = money(300, 4.5);
-  const moneyNeutral = oklchToHex({ l: mode === "light" ? 0.52 : 0.72, c: 0.012, h: brand.h });
+  // "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 moneyNeutral = oklchToHex({
+    l: mode === "light" ? Math.min(0.52, neutralFloor) : Math.max(0.72, neutralFloor),
+    c: 0.012,
+    h: brand.h,
+  });
 
   const tokens: TokenSet = {
     ...surfaces,
@@ -498,6 +553,13 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
     ["bgSurface", t.bgSurface],
     ["bgSurface2", t.bgSurface2],
   ];
+  // A hovered row on the card (`--bg-hover`) carries the same text as the card, and in
+  // light it is the darkest fill that text sits on (0.33, §12.10). Text is measured on
+  // it; the brand fill and the hairline, which are not text, are not.
+  const hover = hoverFill(t);
+  const textGrounds: Array<[string, string]> = [...surfaces, ["bgHover", hover]];
+  // `--brand-muted`, `--brand-bg` and `--brand-bg-hover`, mixed as tokens.css mixes them.
+  const { brandMuted, brandBg, brandBgHover } = brandSoft(t);
 
   const add = (pair: string, fg: string, bg: string, required: number, rule: string) => {
     const ratio = contrast(fg, bg);
@@ -505,21 +567,35 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
   };
 
   for (const [name, bg] of surfaces) {
+    add(`brand on ${name}`, t.brand, bg, 3, "WCAG 1.4.11 graphical object");
+    add(`border on ${name}`, t.border, bg, 1.1, "house rule: a hairline must be findable");
+  }
+  for (const [name, bg] of textGrounds) {
     add(`textPrimary on ${name}`, t.textPrimary, bg, 7, "WCAG 1.4.6 AAA body text");
     add(`textSecondary on ${name}`, t.textSecondary, bg, 4.5, "WCAG 1.4.3 AA body text");
     add(`textMuted on ${name}`, t.textMuted, bg, 4.5, "WCAG 1.4.3 AA body text");
-    add(`brand on ${name}`, t.brand, bg, 3, "WCAG 1.4.11 graphical object");
-    add(`border on ${name}`, t.border, bg, 1.1, "house rule: a hairline must be findable");
+    add(`brandMuted on ${name}`, brandMuted, bg, 4.5, "WCAG 1.4.3 — the brand as text");
     for (const [key, hex] of [
       ["moneyIncome", t.moneyIncome],
       ["moneyExpense", t.moneyExpense],
       ["moneyNet", t.moneyNet],
+      // Not a figure's colour but still printed as one (the numpad's sign, a future
+      // row's amount) — measured since 0.33, when it was found at 4.24:1.
+      ["moneyNeutral", t.moneyNeutral],
     ] as const) {
       add(`${key} on ${name}`, hex, bg, 4.5, "WCAG 1.4.3 — these are rendered as TEXT");
     }
   }
 
   add("brandContrast on brand", t.brandContrast, t.brand, 4.5, "WCAG 1.4.3 AA body text");
+  // A hovered brand button carries the same label (0.33): the derived dark presets
+  // lightened the hover toward their white label and left it at 4.07:1.
+  add("brandContrast on brandHover", t.brandContrast, t.brandHover, 4.5, "WCAG 1.4.3 AA body text");
+  add("brandMuted on brandBg", brandMuted, brandBg, 4.5, "WCAG 1.4.3 — a soft brand chip's label");
+  // The same label on the chip hovered (§12.11): a current link, a selected day. At 70 %
+  // brand the muted text read 4.08–4.42:1 here (Default and Moss light; Ink, Moss, Plum
+  // and Contrast dark).
+  add("brandMuted on brandBgHover", brandMuted, brandBgHover, 4.5, "WCAG 1.4.3 — a hovered soft brand chip's label");
 
   if (semantic) {
     for (const [name, fg] of [
@@ -529,6 +605,7 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
       ["success", semantic.success],
     ] as const) {
       add(`${name} on bgSurface`, fg, t.bgSurface, 4.5, "WCAG 1.4.3 — rendered as text");
+      add(`${name} on bgHover`, fg, hover, 4.5, "WCAG 1.4.3 — rendered as text, on a hovered row");
     }
     add("danger on dangerBg", semantic.danger, semantic.dangerBg, 4.5, "WCAG 1.4.3 — badge text");
     add("warning on warningBg", semantic.warning, semantic.warningBg, 4.5, "WCAG 1.4.3 — badge text");