@eifi1/ui-kit 0.31.1 → 0.32.1

package/src/shell/top-bar-brand.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import { Link as RouterLink } from "react-router";
 import { cn } from "../lib/cn";
+import { FOCUS_RING } from "../components/focus-ring";
 import { useKitLink } from "../i18n/kit-labels";
 import { pickLinkRenderer } from "../components/text-link";
 import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
@@ -58,7 +59,8 @@ export function TopBarBrand({
       href={to}
       className={cn(
         // `relative` contains the sr-only name.
-        "relative flex min-w-0 items-center gap-2 rounded-md font-semibold text-[var(--text-primary)] hover:opacity-80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        "relative flex min-w-0 items-center gap-2 rounded-md font-semibold text-[var(--text-primary)] hover:opacity-80",
+        FOCUS_RING,
         className,
       )}
     >

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

@@ -326,7 +326,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-2 [&_a:focus-visible]:ring-[var(--brand)]";
+          "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)]";
         /** One action or link row — loose, or inside a heading's group. */
         const row = (entry: RowEntry) => (
           <li key={entry.key}>
@@ -374,7 +374,7 @@ export function TopBarActionMenu({
               </MenuSection>
             )}
             {heading && (
-              <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
                 {heading}
               </li>
             )}
@@ -397,7 +397,7 @@ export function TopBarActionMenu({
                     id={headingId}
                     role="presentation"
                     className={cn(
-                      "px-3 pb-0.5 text-[11px] 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-[var(--text-muted)] [overflow-wrap:anywhere]",
                       tight ? "pt-1" : "pt-2.5",
                     )}
                   >

package/src/shell/topbar-controls.tsx

@@ -19,7 +19,7 @@ export const TOPBAR_MENU_ITEM_CLASS =
 /** The small uppercase heading row the top-bar menus share (`heading`). */
 function MenuHeading({ children }: { children: string }) {
   return (
-    <li className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+    <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
       {children}
     </li>
   );
@@ -131,7 +131,7 @@ export function PaletteMenu({
                     </span>
                     <span className="flex min-w-0 flex-col text-start">
                       <span className="truncate">{p.name}</span>
-                      <span className="truncate text-[11px] text-[var(--text-placeholder)]">
+                      <span className="truncate text-caption text-[var(--text-placeholder)]">
                         {p.blurb}
                       </span>
                     </span>
@@ -197,7 +197,7 @@ export function LanguageMenu({
             {active ? (
               <span
                 aria-hidden
-                className={`fi fi-${active.country} inline-block h-[15px] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
+                className={`fi fi-${active.country} inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
               />
             ) : (
               <Globe className="size-5" />
@@ -224,7 +224,7 @@ export function LanguageMenu({
                   <span className="flex items-center gap-2">
                     <span
                       aria-hidden
-                      className={`fi fi-${lang.country} inline-block h-[15px] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
+                      className={`fi fi-${lang.country} inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
                     />
                     {lang.label}
                   </span>

package/src/theme/contrast-tokens.ts

@@ -0,0 +1,112 @@
+import { contrast, oklchToRgb, parseHex, rgbToOklch, toHex } from "./color";
+import type { TokenSet } from "./palette-presets";
+
+/**
+ * The "More contrast" step on a token set (docs/text-size-harmonization.md §5, §10.5).
+ * INTERNAL — `applyTokenSet` and the contrast layer share it; it is not re-exported.
+ *
+ * The step happens HERE, in JS, because the tokens it changes are written inline on
+ * `<html>` by `applyTokenSet`: an inline value beats any `[data-contrast=more]` rule and
+ * any `@media (prefers-contrast: more)` block, so a stylesheet cannot do it (§10.5, the
+ * keksdose review). `--text-placeholder` is a CSS-derived token, and it is written inline
+ * here too rather than redefined per attribute in tokens.css.
+ *
+ * What moves (§5):
+ * - `--text-muted` becomes the set's `--text-secondary`;
+ * - `--text-secondary` moves halfway to `--text-primary`;
+ * - `--text-placeholder` becomes the set's `--text-muted` (4.6–5.5:1 on every shipped
+ *   preset, where the CSS formula gives 2.4–2.8:1) — the order primary > secondary >
+ *   muted > placeholder survives the step;
+ * - `--border` moves toward `--text-primary` until it clears 3:1 against the worst of the
+ *   three surfaces (WCAG 1.4.11, a field's boundary), and never less far than
+ *   `--border-strong`'s 45 % — so every border is at least as strong as a "strong" one was.
+ *   `--border-strong` stays derived in tokens.css and grows with it.
+ */
+
+/** The custom properties a contrast step writes. */
+export const CONTRAST_STEPPED_VARS = ["--text-secondary", "--text-muted", "--text-placeholder", "--border"] as const;
+
+export interface ContrastStep {
+  textSecondary: string;
+  textMuted: string;
+  textPlaceholder: string;
+  border: string;
+}
+
+interface Lab {
+  l: number;
+  a: number;
+  b: number;
+}
+
+function toLab(hex: string): Lab | null {
+  const rgb = parseHex(hex);
+  if (!rgb) return null;
+  const { l, c, h } = rgbToOklch(rgb);
+  const rad = (h * Math.PI) / 180;
+  return { l, a: c * Math.cos(rad), b: c * Math.sin(rad) };
+}
+
+/** `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 {
+  const A = toLab(a);
+  const B = toLab(b);
+  if (!A || !B) return a;
+  const l = A.l * p + B.l * (1 - p);
+  const x = A.a * p + B.a * (1 - p);
+  const y = A.b * p + B.b * (1 - p);
+  const c = Math.hypot(x, y);
+  const h = c < 1e-6 ? 0 : ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
+  return toHex(oklchToRgb({ l, c, h }));
+}
+
+/** WCAG 1.4.11 for a component's boundary. */
+const BORDER_TARGET = 3;
+/** `--border-strong` in tokens.css: 55 % border, 45 % text. */
+const BORDER_STRONG_SHARE = 0.45;
+
+function worstContrast(color: string, t: TokenSet): number {
+  return Math.min(contrast(color, t.bgPage), contrast(color, t.bgSurface), contrast(color, t.bgSurface2));
+}
+
+function steppedBorder(t: TokenSet): string {
+  // The share of `--text-primary` in the border: at least --border-strong's, more until
+  // 3:1. Monotonic in the share (the mix walks from the border to the text, away from
+  // every surface), so a bisection finds the least that clears it.
+  let lo = BORDER_STRONG_SHARE;
+  if (worstContrast(mix(t.border, t.textPrimary, 1 - lo), t) >= BORDER_TARGET) return mix(t.border, t.textPrimary, 1 - lo);
+  let hi = 1;
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    if (worstContrast(mix(t.border, t.textPrimary, 1 - mid), t) >= BORDER_TARGET) hi = mid;
+    else lo = mid;
+  }
+  return mix(t.border, t.textPrimary, 1 - hi);
+}
+
+/** The four stepped values for `t`. Pure. */
+export function contrastStep(t: TokenSet): ContrastStep {
+  return {
+    textSecondary: mix(t.textSecondary, t.textPrimary, 0.5),
+    textMuted: t.textSecondary,
+    textPlaceholder: t.textMuted,
+    border: steppedBorder(t),
+  };
+}
+
+/* ── The token set last written to an element ───────────────────────────── */
+
+const lastWritten = new WeakMap<HTMLElement, TokenSet>();
+
+/** Remember the set `applyTokenSet` wrote, so a contrast change can re-apply it. */
+export function rememberTokenSet(el: HTMLElement, t: TokenSet): void {
+  lastWritten.set(el, t);
+}
+
+/** The set `applyTokenSet` last wrote to `el`, or undefined when nothing did — an app
+ *  without the palette layer, whose base tokens come from tokens.css. */
+export function rememberedTokenSet(el: HTMLElement): TokenSet | undefined {
+  return lastWritten.get(el);
+}

package/src/theme/contrast.ts

@@ -0,0 +1,225 @@
+import { useEffect } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger";
+import { readStored } from "../lib/safe-storage";
+import { useMediaQuery } from "../hooks/use-media-query";
+import { CONTRAST_STEPPED_VARS, contrastStep, rememberedTokenSet } from "./contrast-tokens";
+import { applyTokenSet, DEFAULT_PRESET } from "./palette-presets";
+import type { PersistedAppearanceOptions } from "./text-size";
+
+/**
+ * "More contrast" (docs/text-size-harmonization.md §2.4, §5, §10.5, §10.6): a switch
+ * beside the text size, on by choice or — on "System" — when the device asks for more
+ * contrast (`prefers-contrast: more`). Any text size.
+ *
+ * In force it is `<html data-contrast="more">` (else `"standard"`), which does two things:
+ * - the inline colour tokens are re-written one step stronger (`applyTokenSet`'s
+ *   contrast flag — see contrast-tokens.ts for what moves and why it is JS);
+ * - tokens.css raises `--focus-ring-width` from 2 to 3 px and turns on the `contrast:`
+ *   variant for anything else a component wants to change.
+ *
+ * The names below are frozen like the text size's: server-kit's `CONTRAST_MODES`, the
+ * stored format, the attribute.
+ */
+
+/** The stored choices (§10.6): server-kit's `CONTRAST_MODES`. "system" IS a stored value
+ *  — the PATCH rule refuses an explicit null, so null means only "never chosen". */
+export const CONTRAST_MODES = ["system", "standard", "more"] as const;
+
+export type ContrastMode = (typeof CONTRAST_MODES)[number];
+
+/** What is in force on `<html data-contrast>`: a mode with "system" resolved. */
+export type ContrastLevel = "standard" | "more";
+
+const CONTRAST_ATTRIBUTE = "data-contrast";
+const PREFERS_MORE_QUERY = "(prefers-contrast: more)";
+
+export function isContrastMode(value: unknown): value is ContrastMode {
+  return value === "system" || value === "standard" || value === "more";
+}
+
+/** The mode in force: **this device's own choice → the account's → "system"** (§2.6).
+ *  The one order the pre-paint call, the apply hook and `useAccountAppearance` share. */
+export function resolveContrastMode(device: unknown, account?: unknown): ContrastMode {
+  if (isContrastMode(device)) return device;
+  if (isContrastMode(account)) return account;
+  return "system";
+}
+
+/** Whether the device asks for more contrast now. False without `matchMedia`. */
+export function prefersMoreContrast(): boolean {
+  try {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function"
+      ? window.matchMedia(PREFERS_MORE_QUERY).matches
+      : false;
+  } catch {
+    return false;
+  }
+}
+
+/** A mode to the level it puts on `<html>`; "system" asks the device (or takes
+ *  `prefersMore`, when the caller already knows). */
+export function contrastLevel(mode: ContrastMode, prefersMore: boolean = prefersMoreContrast()): ContrastLevel {
+  return mode === "more" || (mode === "system" && prefersMore) ? "more" : "standard";
+}
+
+/** The level `<html>` carries now; "standard" without one. */
+export function readContrastLevel(): ContrastLevel {
+  if (typeof document === "undefined") return "standard";
+  return document.documentElement.getAttribute(CONTRAST_ATTRIBUTE) === "more" ? "more" : "standard";
+}
+
+/**
+ * Re-write the contrast-dependent tokens on `el` for its current `data-contrast`.
+ *
+ * With a palette layer (`applyTokenSet` has written a set here), that set is applied
+ * again and steps itself. Without one — an app whose base tokens come from tokens.css,
+ * like Kurvenschmiede's — the four stepped tokens are written over the stylesheet for
+ * the default preset in the current light/dark, or removed again.
+ */
+function reapplyContrastTokens(el: HTMLElement): void {
+  const written = rememberedTokenSet(el);
+  if (written) {
+    applyTokenSet(el, written);
+    return;
+  }
+  for (const name of CONTRAST_STEPPED_VARS) el.style.removeProperty(name);
+  if (el.getAttribute(CONTRAST_ATTRIBUTE) !== "more") return;
+  const step = contrastStep(DEFAULT_PRESET[el.classList.contains("dark") ? "dark" : "light"]);
+  el.style.setProperty("--text-secondary", step.textSecondary);
+  el.style.setProperty("--text-muted", step.textMuted);
+  el.style.setProperty("--text-placeholder", step.textPlaceholder);
+  el.style.setProperty("--border", step.border);
+}
+
+/** Put `level` on `<html>` and re-write the colour tokens for it. */
+export function applyContrast(level: ContrastLevel): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  root.setAttribute(CONTRAST_ATTRIBUTE, level);
+  reapplyContrastTokens(root);
+}
+
+/* ── Storage: the frozen format, the pre-paint call ─────────────────────── */
+
+/**
+ * What a contrast store persists under its key — FROZEN, like the text size's:
+ *
+ *     {"state":{"contrast":"more"},"version":1}
+ *
+ * `contrast` is one of {@link CONTRAST_MODES}, or `null` / absent when this device never
+ * chose.
+ */
+export interface PersistedContrast {
+  state?: { contrast?: ContrastMode | null };
+  version?: number;
+}
+
+/** This device's own choice under `storageKey`, or `null` when it never chose. */
+export function readPersistedContrast(storageKey: string): ContrastMode | null {
+  try {
+    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedContrast | null;
+    const mode = blob?.state?.contrast;
+    return isContrastMode(mode) ? mode : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pre-paint (§10.3, §10.5): this device's choice under `storageKey` — else the account's
+ * last known value, else "system" — resolved against `prefers-contrast` and applied
+ * BEFORE `createRoot`. Call it next to `applyPersistedPalette`, in EITHER order — the
+ * palette steps itself when `data-contrast` is already set, and this re-applies the
+ * palette's set when it is not; no app has to put one first (0.32.1, keksdose's 0.32
+ * report asked which). Returns the level applied.
+ */
+export function applyPersistedContrast(storageKey: string, options: PersistedAppearanceOptions = {}): ContrastLevel {
+  let account: unknown;
+  try {
+    account = options.account?.();
+  } catch {
+    account = undefined;
+  }
+  const level = contrastLevel(resolveContrastMode(readPersistedContrast(storageKey), account));
+  applyContrast(level);
+  return level;
+}
+
+/* ── The store ──────────────────────────────────────────────────────────── */
+
+export interface ContrastState {
+  /** This device's own choice (persisted), or `null` when it never chose — then the
+   *  account's value applies, else "system". */
+  contrast: ContrastMode | null;
+  /** Store this device's choice; `null` forgets it. */
+  setContrast: (contrast: ContrastMode | null) => void;
+}
+
+export interface ApplyContrastOptions {
+  /** The account's value (`/auth/me`'s `contrast`): it applies while this device has no
+   *  choice of its own. */
+  account?: string | null;
+}
+
+/**
+ * Build a contrast store bound to a consumer-supplied localStorage key, shaped like
+ * `createThemeStore` and {@link createTextSizeStore} (§6). It holds the DEVICE's choice;
+ * the account's value comes in through `useApplyContrast({ account })`.
+ *
+ * `useApplyContrast` — mount it once near the root, beside `useApplyPalette`:
+ * - puts the level on `<html>` and steps the tokens;
+ * - on "System", follows `prefers-contrast: more` live (§10.5);
+ * - without a palette layer, re-writes the stepped tokens when the light/dark class
+ *   changes, since they differ per theme.
+ *
+ * The persisted format is {@link PersistedContrast}, and frozen.
+ */
+export function createContrastStore(storageKey: string) {
+  const useContrastStore = create<ContrastState>()(
+    logger(
+      persist(
+        (set) => ({
+          contrast: null,
+          setContrast: (contrast) => set({ contrast: isContrastMode(contrast) ? contrast : null }),
+        }),
+        {
+          name: storageKey,
+          version: 1,
+          partialize: (s) => ({ contrast: s.contrast }),
+          merge: (persisted, current) => {
+            const value = (persisted as { contrast?: unknown } | null)?.contrast;
+            return { ...current, contrast: isContrastMode(value) ? value : null };
+          },
+        },
+      ),
+      "contrast",
+    ),
+  );
+
+  function useApplyContrast({ account }: ApplyContrastOptions = {}): ContrastLevel {
+    const device = useContrastStore((s) => s.contrast);
+    // Subscribed whatever the mode (hooks cannot be skipped); only "system" reads it.
+    const prefersMore = useMediaQuery(PREFERS_MORE_QUERY, false);
+    const level = contrastLevel(resolveContrastMode(device, account), prefersMore);
+    useEffect(() => {
+      applyContrast(level);
+    }, [level]);
+    // Without a palette layer the stepped tokens are per theme: follow `.dark`.
+    useEffect(() => {
+      if (typeof MutationObserver === "undefined") return;
+      const root = document.documentElement;
+      const observer = new MutationObserver(() => {
+        if (!rememberedTokenSet(root)) reapplyContrastTokens(root);
+      });
+      observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+      return () => observer.disconnect();
+    }, []);
+    return level;
+  }
+
+  return { useContrastStore, useApplyContrast };
+}
+
+export type ContrastStore = ReturnType<typeof createContrastStore>;

package/src/theme/palette-presets.ts

@@ -15,6 +15,7 @@
 // (the default preset here mirrors those exactly).
 
 import type { HeatStops } from "./chart-palette";
+import { contrastStep, rememberTokenSet } from "./contrast-tokens";
 
 export interface TokenSet {
   // Backgrounds & chrome
@@ -740,15 +741,34 @@ export function presetById(id: string): PalettePreset {
  * have been silent and only a dead function would have noticed. The list is gone;
  * the test beside this asserts instead that every field of a `TokenSet` reaches the
  * element, which is what that list was standing in for.
+ *
+ * **More contrast (0.32, docs/text-size-harmonization.md §5, §10.5).** With `contrast`
+ * the text and border tokens are written one step stronger, and `--text-placeholder` —
+ * otherwise derived in tokens.css — is written inline too; without it that inline
+ * placeholder is removed again, so the stylesheet's formula applies. The step is made
+ * HERE because these tokens are inline: no `[data-contrast=more]` rule could beat them.
+ *
+ * `contrast` defaults to the element's own `data-contrast="more"`, which the contrast
+ * layer (`applyContrast`, `useApplyContrast`) sets first. That is how the palette and the
+ * contrast cooperate without knowing each other: a palette change re-applies through
+ * here and keeps the contrast, and a contrast change re-applies the set remembered here.
  */
-export function applyTokenSet(el: HTMLElement, t: TokenSet): void {
+export function applyTokenSet(
+  el: HTMLElement,
+  t: TokenSet,
+  contrast: boolean = el.getAttribute("data-contrast") === "more",
+): void {
+  rememberTokenSet(el, t);
+  const step = contrast ? contrastStep(t) : null;
   el.style.setProperty("--bg-page", t.bgPage);
   el.style.setProperty("--bg-surface", t.bgSurface);
   el.style.setProperty("--bg-surface-2", t.bgSurface2);
-  el.style.setProperty("--border", t.border);
+  el.style.setProperty("--border", step?.border ?? t.border);
   el.style.setProperty("--text-primary", t.textPrimary);
-  el.style.setProperty("--text-secondary", t.textSecondary);
-  el.style.setProperty("--text-muted", t.textMuted);
+  el.style.setProperty("--text-secondary", step?.textSecondary ?? t.textSecondary);
+  el.style.setProperty("--text-muted", step?.textMuted ?? t.textMuted);
+  if (step) el.style.setProperty("--text-placeholder", step.textPlaceholder);
+  else el.style.removeProperty("--text-placeholder");
   el.style.setProperty("--brand", t.brand);
   el.style.setProperty("--brand-hover", t.brandHover);
   el.style.setProperty("--brand-contrast", t.brandContrast);

package/src/theme/palette-store.ts

@@ -60,7 +60,12 @@ export function createPaletteStore(
   /** Apply the active preset's tokens to <html> as inline CSS custom properties,
    *  re-applying when the preset or the light/dark theme changes. Tailwind v4
    *  strips a bare root token block from the bundle, so this inline write from
-   *  the TS source of truth is what actually drives the colours. */
+   *  the TS source of truth is what actually drives the colours.
+   *
+   *  0.32: keeps More contrast. `applyTokenSet` reads `<html data-contrast>`, which the
+   *  contrast store sets, and steps the tokens itself; the contrast store re-applies
+   *  the set written here when the contrast changes (docs/text-size-harmonization.md
+   *  §10.5). Neither store needs the other. */
   function useApplyPalette(): void {
     const id = usePalette((s) => s.id);
     const mode = useTheme((s) => s.mode);