@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/theme/contrast-tokens.ts

@@ -1,4 +1,4 @@
-import { contrast, oklchToRgb, parseHex, rgbToOklch, toHex } from "./color";
+import { contrast, hexToOklch, luminance, oklchToHex, oklchToRgb, parseHex, rgbToOklch, solveLightness, toHex } from "./color";
 import type { TokenSet } from "./palette-presets";
 
 /**
@@ -20,17 +20,48 @@ import type { TokenSet } from "./palette-presets";
  * - `--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.
+ *   `--border-strong` stays derived in tokens.css and grows with it;
+ * - in a LIGHT set only (0.36, docs/colour-roles-harmonization.md §13): the well
+ *   (`--bg-surface-2`) becomes {@link WELL_INK_MORE} of `--text-primary` mixed into the
+ *   card, and each of the four money colours that falls under 4.5:1 on that well is
+ *   solved darker at its own hue and chroma. The border above is solved against the
+ *   stepped well. A dark set's well stands 1.11–1.13:1 from its card already, and its
+ *   money has no room: nothing of it steps.
+ *
+ * What does NOT move here, because it is not inline: the light status, hue and field-sync
+ * literals and `--bg-active` step in tokens.css's `:root[data-contrast="more"]:not(.dark)`
+ * block, solved over these stepped wells.
  */
 
-/** The custom properties a contrast step writes. */
-export const CONTRAST_STEPPED_VARS = ["--text-secondary", "--text-muted", "--text-placeholder", "--border"] as const;
+/** The custom properties a contrast step writes. The last five only for a light set. */
+export const CONTRAST_STEPPED_VARS = [
+  "--text-secondary",
+  "--text-muted",
+  "--text-placeholder",
+  "--border",
+  "--bg-surface-2",
+  "--money-income",
+  "--money-expense",
+  "--money-net",
+  "--money-neutral",
+] as const;
+
+/** The light well under More contrast and the money that reads on it (§13.4). */
+export interface WellStep {
+  bgSurface2: string;
+  moneyIncome: string;
+  moneyExpense: string;
+  moneyNet: string;
+  moneyNeutral: string;
+}
 
 export interface ContrastStep {
   textSecondary: string;
   textMuted: string;
   textPlaceholder: string;
   border: string;
+  /** The stepped well and money, or null for a dark set (which does not step them). */
+  well: WellStep | null;
 }
 
 interface Lab {
@@ -82,6 +113,63 @@ export function hoverFill(t: Pick<TokenSet, "textPrimary" | "bgSurface">): strin
   return mix(t.textPrimary, t.bgSurface, HOVER_INK);
 }
 
+/**
+ * The light well under More contrast: this share of `--text-primary` mixed into the card,
+ * `--bg-hover`'s formula at a larger share (0.36, docs/colour-roles-harmonization.md §13).
+ *
+ * In light the well is the page (§5.3), 1.09–1.11:1 from the card. At 10 % it stands
+ * 1.19–1.24:1 from it, about twice that. The rule it is held to: **the stepped well stands
+ * at least 1.17:1 from the card**, two of the hover rule's 1.08 steps; 9 % is the least
+ * that clears it in every shipped preset, with no room. The step cannot ship alone: on a
+ * 10 % well money, status and two hues read 4.07–4.28:1, so the money is solved with it
+ * here and the status and hue literals in tokens.css.
+ */
+export const WELL_INK_MORE = 0.1;
+
+/** The least the stepped light well stands from the card (§13.3, decision 2). */
+export const WELL_STEP_MIN = 1.17;
+
+/** True when `t` is a light set: its body ink darker than its card. */
+function isLightSet(t: Pick<TokenSet, "textPrimary" | "bgSurface">): boolean | null {
+  const ink = parseHex(t.textPrimary);
+  const card = parseHex(t.bgSurface);
+  if (!ink || !card) return null;
+  return luminance(ink) < luminance(card);
+}
+
+/** Money as text: WCAG 1.4.3 AA. */
+const MONEY_TARGET = 4.5;
+
+/** `color` as it is when it clears 4.5:1 on `well`, else solved darker at its own hue and
+ *  chroma until it does — measured on the hex (`solveLightness`). */
+function moneyOn(color: string, well: string): string {
+  if (contrast(color, well) >= MONEY_TARGET) return color;
+  const lch = hexToOklch(color);
+  const bg = parseHex(well);
+  if (!lch || !bg) return color;
+  const l = solveLightness(MONEY_TARGET, bg, lch.h, lch.c, "darker");
+  return oklchToHex({ l, c: lch.c, h: lch.h });
+}
+
+/** The light well under More contrast for `t`, or null for a dark set (or one whose ink or
+ *  card is not hex, which cannot be mixed). The deriver solves the brand against it. */
+export function steppedWellFill(t: Pick<TokenSet, "textPrimary" | "bgSurface">): string | null {
+  return isLightSet(t) ? mix(t.textPrimary, t.bgSurface, WELL_INK_MORE) : null;
+}
+
+/** The stepped well and money of a light set, or null (see {@link steppedWellFill}). */
+function wellStep(t: TokenSet): WellStep | null {
+  const well = steppedWellFill(t);
+  if (!well) return null;
+  return {
+    bgSurface2: well,
+    moneyIncome: moneyOn(t.moneyIncome, well),
+    moneyExpense: moneyOn(t.moneyExpense, well),
+    moneyNet: moneyOn(t.moneyNet, well),
+    moneyNeutral: moneyOn(t.moneyNeutral, well),
+  };
+}
+
 /**
  * `--brand-muted` in tokens.css: this share of `--brand` mixed into `--text-primary`.
  *
@@ -118,32 +206,38 @@ 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));
+/** The worst of the three surfaces; `well`, when the step has one, in place of the set's. */
+function worstContrast(color: string, t: TokenSet, well: string): number {
+  return Math.min(contrast(color, t.bgPage), contrast(color, t.bgSurface), contrast(color, well));
 }
 
-function steppedBorder(t: TokenSet): string {
+function steppedBorder(t: TokenSet, well: WellStep | null): 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.
+  // every surface), so a bisection finds the least that clears it. Against the stepped
+  // light well (§13.4), which is the darkest surface under More contrast.
+  const surface2 = well?.bgSurface2 ?? t.bgSurface2;
   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);
+  if (worstContrast(mix(t.border, t.textPrimary, 1 - lo), t, surface2) >= 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;
+    if (worstContrast(mix(t.border, t.textPrimary, 1 - mid), t, surface2) >= BORDER_TARGET) hi = mid;
     else lo = mid;
   }
   return mix(t.border, t.textPrimary, 1 - hi);
 }
 
-/** The four stepped values for `t`. Pure. */
+/** The stepped values for `t`: the four text and line tokens, and for a light set the
+ *  well and money (`well`, null in dark). Pure. */
 export function contrastStep(t: TokenSet): ContrastStep {
+  const well = wellStep(t);
   return {
     textSecondary: mix(t.textSecondary, t.textPrimary, 0.5),
     textMuted: t.textSecondary,
     textPlaceholder: t.textMuted,
-    border: steppedBorder(t),
+    border: steppedBorder(t, well),
+    well,
   };
 }
 

package/src/theme/contrast.ts

@@ -3,6 +3,7 @@ import { create } from "zustand";
 import { persist } from "zustand/middleware";
 import { logger } from "../lib/logger";
 import { readStored } from "../lib/safe-storage";
+import { registerDeviceSetting } from "../lib/device-settings";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { CONTRAST_STEPPED_VARS, contrastStep, rememberedTokenSet } from "./contrast-tokens";
 import { applyTokenSet, DEFAULT_PRESET } from "./palette-presets";
@@ -16,8 +17,10 @@ import type { PersistedAppearanceOptions } from "./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.
+ * - tokens.css raises `--focus-ring-width` from 2 to 3 px, in light deepens the status,
+ *   hue and field-sync literals and `--bg-active` to read on the stepped well (0.36,
+ *   colour-roles §13), 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.
@@ -75,8 +78,15 @@ export function readContrastLevel(): ContrastLevel {
  *
  * 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.
+ * like Kurvenschmiede's — the stepped tokens are written over the stylesheet for the
+ * default preset in the current light/dark, or removed again: the four text and line
+ * tokens in both modes, and in light the well and the four money colours too (0.36,
+ * docs/colour-roles-harmonization.md §13.3 decision 10). In dark those five stay removed,
+ * so the stylesheet's dark well and money paint.
+ *
+ * It never calls `applyTokenSet` here: that would remember a token set on `<html>`, and
+ * this app would then take the palette branch above, which a theme switch does not re-run
+ * (the class observer in `useApplyContrast` re-writes only while nothing is remembered).
  */
 function reapplyContrastTokens(el: HTMLElement): void {
   const written = rememberedTokenSet(el);
@@ -91,6 +101,14 @@ function reapplyContrastTokens(el: HTMLElement): void {
   el.style.setProperty("--text-muted", step.textMuted);
   el.style.setProperty("--text-placeholder", step.textPlaceholder);
   el.style.setProperty("--border", step.border);
+  // One line per variable, not a loop: the step's fields are not the variables' names.
+  if (step.well) {
+    el.style.setProperty("--bg-surface-2", step.well.bgSurface2);
+    el.style.setProperty("--money-income", step.well.moneyIncome);
+    el.style.setProperty("--money-expense", step.well.moneyExpense);
+    el.style.setProperty("--money-net", step.well.moneyNet);
+    el.style.setProperty("--money-neutral", step.well.moneyNeutral);
+  }
 }
 
 /** Put `level` on `<html>` and re-write the colour tokens for it. */
@@ -197,6 +215,14 @@ export function createContrastStore(storageKey: string) {
       "contrast",
     ),
   );
+  // Reset this device's settings (docs/settings-harmonization.md §11.4): no choice on
+  // this device, so `useApplyContrast` re-resolves to the account's mode, else "system",
+  // and re-steps the tokens.
+  registerDeviceSetting({
+    key: storageKey,
+    kind: "appearance",
+    reset: () => useContrastStore.getState().setContrast(null),
+  });
 
   function useApplyContrast({ account }: ApplyContrastOptions = {}): ContrastLevel {
     const device = useContrastStore((s) => s.contrast);

package/src/theme/palette-derive.ts

@@ -13,7 +13,8 @@ import {
   solveLightness,
 } from "./color";
 import type { CvdType, Oklch } from "./color";
-import { brandSoft, hoverFill } from "./contrast-tokens";
+import type { ContrastLevel } from "./contrast";
+import { brandSoft, contrastStep, hoverFill, steppedWellFill, WELL_STEP_MIN } from "./contrast-tokens";
 
 /**
  * Build a whole palette from one brand colour, plus any number of colours pinned by
@@ -104,6 +105,8 @@ export interface ContrastReport {
 export interface DerivedPalette {
   tokens: TokenSet;
   semantic: SemanticTokens;
+  /** {@link auditPalette} at both contrast levels: the More-contrast checks carry a
+   *  " (More contrast)" suffix (0.36). */
   audit: ContrastReport;
   /** Compromises the deriver had to make, in plain words. Never silent. */
   warnings: string[];
@@ -310,15 +313,24 @@ export function derivePalette({
   // ── 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.
+  //
+  // In light the worst surface includes More contrast's well (0.36, colour-roles §13.4):
+  // 10 % ink into the card, darker than the page. The step is applied, not derived, but
+  // the brand is not stepped, so both brand solves measure there too and a derived
+  // palette holds at both levels.
+  const moreWell = steppedWellFill({ textPrimary, bgSurface: surfaces.bgSurface });
+  const brandGround = moreWell
+    ? [worstSurface, moreWell].reduce((a, b) => (contrast(a, "#000000") < contrast(b, "#000000") ? a : b))
+    : worstSurface;
   const brandChroma = Math.max(brand.c, 0.06);
-  const brandRatio = contrast(anchors.brand, worstSurface);
+  const brandRatio = contrast(anchors.brand, brandGround);
   // 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.
   let brandHex =
     brandRatio >= 3
       ? toHex(parseHex(anchors.brand)!)
-      : solveAgainst(brand.h, brandChroma, 3, worstSurface, mode);
+      : solveAgainst(brand.h, brandChroma, 3, brandGround, mode);
   if (brandRatio < 3) {
     warnings.push(
       `brand ${anchors.brand} sits at ${brandRatio.toFixed(2)}:1 against the ${mode} surfaces, ` +
@@ -338,6 +350,8 @@ export function derivePalette({
       contrast(soft.brandMuted, worstText),
       contrast(soft.brandMuted, soft.brandBg),
       contrast(soft.brandMuted, soft.brandBgHover),
+      // …and on More contrast's light well, where a link button reads it (§13.3).
+      moreWell ? contrast(soft.brandMuted, moreWell) : Infinity,
     );
   };
   for (let i = 0; i < 40 && brandMutedWorst(brandHex) < 4.5; i++) {
@@ -525,7 +539,15 @@ export function derivePalette({
     heat: deriveHeat(moneyIncome, moneyExpense, surfaces, mode),
   };
 
-  return { tokens, semantic, audit: auditPalette(tokens, semantic), warnings };
+  // Audited at both contrast levels (0.36, colour-roles §13.5): More contrast steps the
+  // text, the border and, in light, the well and money of this set. The derived semantic
+  // colours are audited at Standard only: they are solved for the standard grounds, and
+  // only tokens.css's shipped literals step for the darker well.
+  const standard = auditPalette(tokens, semantic);
+  const more = auditPalette(tokens, undefined, { level: "more" });
+  const checks = [...standard.checks, ...more.checks];
+  const failures = checks.filter((c) => !c.passes);
+  return { tokens, semantic, audit: { checks, failures, passes: failures.length === 0 }, warnings };
 }
 
 /**
@@ -560,8 +582,40 @@ function deriveHeat(
  * This is the part the shipped presets were missing. `derivePalette` runs it on the way
  * out, and the preset test runs it over everything the package ships, so a palette that
  * does not hold up cannot be merged with a comment claiming that it does.
+ *
+ * **`level: "more"`** (0.36, docs/colour-roles-harmonization.md §13.5) measures the set as
+ * More contrast paints it: the stepped secondary, muted and border, and in a light set the
+ * stepped well (as `bgSurface2`) and money — the same pairs, named with a " (More
+ * contrast)" suffix. Two things change with the level: the border is a field's boundary
+ * there, held to WCAG 1.4.11's 3:1 rather than the hairline's 1.1, and a light set's well
+ * must stand {@link WELL_STEP_MIN}:1 from the card. Pass `semantic` with tokens.css's More
+ * literals for a light set (the status colours step there); the status text is then
+ * measured on the stepped well too.
  */
-export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastReport {
+export function auditPalette(
+  set: TokenSet,
+  semantic?: SemanticTokens,
+  options: { level?: ContrastLevel } = {},
+): ContrastReport {
+  const more = options.level === "more";
+  const step = more ? contrastStep(set) : null;
+  // The set as it paints at this level: what `applyTokenSet` writes for it.
+  const t: TokenSet = step
+    ? {
+        ...set,
+        textSecondary: step.textSecondary,
+        textMuted: step.textMuted,
+        border: step.border,
+        ...(step.well && {
+          bgSurface2: step.well.bgSurface2,
+          moneyIncome: step.well.moneyIncome,
+          moneyExpense: step.well.moneyExpense,
+          moneyNet: step.well.moneyNet,
+          moneyNeutral: step.well.moneyNeutral,
+        }),
+      }
+    : set;
+  const suffix = more ? " (More contrast)" : "";
   const checks: ContrastCheck[] = [];
   const surfaces: Array<[string, string]> = [
     ["bgPage", t.bgPage],
@@ -585,12 +639,17 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
   const add = (pair: string, fg: string, bg: string, required: number, rule: string) => {
     const ratio = contrast(fg, bg);
     const slack = MIXED.test(pair) ? 0.05 : 0;
-    checks.push({ pair, ratio, required, rule, passes: ratio >= required - slack });
+    checks.push({ pair: pair + suffix, ratio, required, rule, passes: ratio >= required - slack });
   };
 
   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");
+    if (more) add(`border on ${name}`, t.border, bg, 3, "WCAG 1.4.11 — under More contrast a border bounds a field");
+    else add(`border on ${name}`, t.border, bg, 1.1, "house rule: a hairline must be findable");
+  }
+  // The stepped light well, a hex `applyTokenSet` writes (§13.3, decision 2).
+  if (step?.well) {
+    add("bgSurface2 on bgSurface", t.bgSurface2, t.bgSurface, WELL_STEP_MIN, "house rule: the well stands two hover steps from the card");
   }
   for (const [name, bg] of textGrounds) {
     add(`textPrimary on ${name}`, t.textPrimary, bg, 7, "WCAG 1.4.6 AAA body text");
@@ -628,6 +687,8 @@ export function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastRe
     ] 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");
+      // The darker light well the More literals were solved for (§13.3).
+      if (step?.well) add(`${name} on bgSurface2`, fg, t.bgSurface2, 4.5, "WCAG 1.4.3 — rendered as text, on the well");
     }
     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");