@multiplatform.one/theme 7.34.3 → 7.35.0

package/src/theme/readableColor.spec.ts

@@ -1,173 +1,80 @@
 import { describe, expect, it } from "vitest";
-import {
-  resolveAaSolidFill,
-  resolveAccentTintedSurface,
-  resolveLegibleInkOn,
-} from "./readableColor";
+import { resolveAccentTintedSurface, resolveLegibleInkOn } from "./readableColor";
 import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
 
-// The stock accent ramp (defaults/accent.ts) as the theme resolves it.
-const lightAccent = [
-  "hsla(250, 50%, 62%, 1)",
-  "hsla(250, 50%, 58%, 1)",
-  "hsla(250, 50%, 54%, 1)",
-  "hsla(250, 50%, 48%, 1)",
-  "hsla(250, 50%, 46%, 1)",
-  "hsla(250, 50%, 44%, 1)",
-  "hsla(250, 50%, 42%, 1)",
-  "hsla(250, 50%, 40%, 1)",
-  "hsla(250, 50%, 38%, 1)",
-  "hsla(250, 50%, 36%, 1)",
-  "hsla(250, 50%, 95%, 1)",
-  "hsla(250, 50%, 98%, 1)",
-];
-const darkAccent = [
-  "hsla(250, 50%, 35%, 1)",
-  "hsla(250, 50%, 38%, 1)",
-  "hsla(250, 50%, 41%, 1)",
-  "hsla(250, 50%, 43%, 1)",
-  "hsla(250, 50%, 46%, 1)",
-  "hsla(250, 50%, 49%, 1)",
-  "hsla(250, 50%, 52%, 1)",
-  "hsla(250, 50%, 54%, 1)",
-  "hsla(250, 50%, 57%, 1)",
-  "hsla(250, 50%, 60%, 1)",
-  "hsla(250, 50%, 90%, 1)",
-  "hsla(250, 50%, 95%, 1)",
-];
-
 const lightPaper = "#ffffff";
 const lightInk = "#242226";
 const darkPaper = "#161519";
 const darkInk = "#f0eff1";
-
 const lum = (raw: string) => relativeLuminance(normalizeToHex(raw)!);
 
-describe("resolveAccentTintedSurface", () => {
-  it("takes the ramp's pale surface end in a light scheme", () => {
-    const tint = resolveAccentTintedSurface({
-      steps: lightAccent,
-      paper: lightPaper,
-      ink: lightInk,
-    });
-    expect(tint).toBe(lightAccent[10]);
-  });
-
-  it("takes the ramp's deep surface end in a dark scheme", () => {
-    const tint = resolveAccentTintedSurface({ steps: darkAccent, paper: darkPaper, ink: darkInk });
-    expect(tint).toBe(darkAccent[0]);
-  });
-
-  // The bug this rule replaced: keying the pick off a SURFACE token let a tint
-  // sub-theme (which re-ramps surfaces) slide the chip a step per tint. Scheme
-  // polarity comes from the paper/ink anchors, which a tint leaves alone.
-  it("does not drift when surrounding surfaces are re-ramped by a tint", () => {
-    const untinted = resolveAccentTintedSurface({
-      steps: lightAccent,
-      paper: lightPaper,
-      ink: lightInk,
-    });
-    for (const tintedPaper of ["#fffce8", "#fff8f8", "#f2fbf5"]) {
-      expect(
-        resolveAccentTintedSurface({ steps: lightAccent, paper: tintedPaper, ink: lightInk }),
-      ).toBe(untinted);
-    }
-  });
-
-  it("stays a SURFACE tier — never the solid an accent CTA takes", () => {
-    // The solid is accentBackground (= the ramp's mid, palette-shape solid).
-    const lightSolid = lightAccent[2];
-    const darkSolid = darkAccent[9];
-    expect(
-      resolveAccentTintedSurface({ steps: lightAccent, paper: lightPaper, ink: lightInk }),
-    ).not.toBe(lightSolid);
-    expect(
-      resolveAccentTintedSurface({ steps: darkAccent, paper: darkPaper, ink: darkInk }),
-    ).not.toBe(darkSolid);
-  });
+function hsl(raw: string) {
+  const hex = normalizeToHex(raw)!;
+  const [r, g, b] = [1, 3, 5].map((offset) => parseInt(hex.slice(offset, offset + 2), 16) / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  const hue =
+    delta === 0
+      ? 0
+      : max === r
+        ? ((g - b) / delta) % 6
+        : max === g
+          ? (b - r) / delta + 2
+          : (r - g) / delta + 4;
+  return { hue: (hue * 60 + 360) % 360, lightness: (max + min) * 50 };
+}
+
+const v5Schemes = [
+  {
+    scheme: "light",
+    paper: "hsla(0, 0%, 100%, 1)",
+    solid: "hsla(0, 0%, 10%, 1)",
+    ink: "hsla(0, 0%, 2%, 1)",
+  },
+  {
+    scheme: "dark",
+    paper: "hsla(0, 0%, 4%, 1)",
+    solid: "hsla(0, 0%, 45%, 1)",
+    ink: "hsla(0, 0%, 100%, 1)",
+  },
+];
 
-  it("keeps a luminance-picked label readable on the tint in both schemes", () => {
-    const cases = [
-      { steps: lightAccent, paper: lightPaper, ink: lightInk },
-      { steps: darkAccent, paper: darkPaper, ink: darkInk },
-    ];
-    for (const c of cases) {
-      const tint = resolveAccentTintedSurface(c)!;
-      const best = Math.max(
-        contrastRatio(lum(tint), lum(c.paper)),
-        contrastRatio(lum(tint), lum(c.ink)),
-      );
-      expect(best).toBeGreaterThanOrEqual(4.5);
-    }
+describe("resolveAccentTintedSurface", () => {
+  it.each(v5Schemes)("keeps the $scheme v5 wash near the paper", ({ scheme, solid, paper }) => {
+    const wash = resolveAccentTintedSurface({ solid, paper })!;
+    expect(wash).toMatch(/^#[0-9a-f]{6}$/);
+    const contrast = contrastRatio(lum(wash), lum(paper));
+    expect(contrast).toBeGreaterThanOrEqual(1.18);
+    expect(contrast).toBeLessThanOrEqual(1.3);
+    if (scheme === "light") expect(hsl(wash).lightness).toBeGreaterThan(85);
+    else expect(lum(wash)).toBeGreaterThan(lum(paper));
   });
 
-  it("returns undefined when the accent ramp or an anchor is missing", () => {
-    expect(
-      resolveAccentTintedSurface({ steps: [], paper: lightPaper, ink: lightInk }),
-    ).toBeUndefined();
-    expect(
-      resolveAccentTintedSurface({ steps: lightAccent, paper: undefined, ink: lightInk }),
-    ).toBeUndefined();
-    expect(
-      resolveAccentTintedSurface({
-        steps: Array.from({ length: 12 }, () => "var(--nope)"),
-        paper: lightPaper,
-        ink: lightInk,
-      }),
-    ).toBeUndefined();
+  it("retains the hue of a chromatic solid in a pale wash", () => {
+    const solid = "#634fc4";
+    const wash = resolveAccentTintedSurface({ solid, paper: "#ffffff" })!;
+    const hueDistance = Math.abs(hsl(wash).hue - hsl(solid).hue);
+    expect(Math.min(hueDistance, 360 - hueDistance)).toBeLessThan(10);
+    expect(hsl(wash).lightness).toBeGreaterThan(85);
   });
-});
 
-describe("resolveAaSolidFill", () => {
-  it("keeps the preferred solid when it already clears the text floor", () => {
-    const solids = lightAccent.slice(0, 10).map((value, i) => ({
-      token: `$accent${i + 1}`,
-      value,
-    }));
-    // Stock light accentBackground is the mid solid (step 3, 6.09:1 on paper).
+  it.each(v5Schemes)("keeps an anchor readable on the $scheme v5 wash", ({ solid, paper, ink }) => {
+    const wash = resolveAccentTintedSurface({ solid, paper })!;
     expect(
-      resolveAaSolidFill({
-        preferred: { token: "$accentBackground", value: lightAccent[2] },
-        solids,
-        paper: lightPaper,
-        ink: lightInk,
-      }),
-    ).toBe("$accentBackground");
+      Math.max(contrastRatio(lum(wash), lum(paper)), contrastRatio(lum(wash), lum(ink))),
+    ).toBeGreaterThanOrEqual(4.5);
   });
 
-  it("walks off the dark mid-solid that tops out at 4.02:1", () => {
-    const solids = darkAccent.slice(0, 10).map((value, i) => ({
-      token: `$accent${i + 1}`,
-      value,
-    }));
-    const token = resolveAaSolidFill({
-      preferred: { token: "$accentBackground", value: darkAccent[9] },
-      solids,
-      paper: darkPaper,
-      ink: darkInk,
-    });
-    expect(token).not.toBe("$accentBackground");
-    const picked = solids.find((s) => s.token === token);
-    expect(picked?.value).toBeTruthy();
-    const fillLum = lum(picked!.value!);
-    const best = Math.max(
-      contrastRatio(fillLum, lum(darkPaper)),
-      contrastRatio(fillLum, lum(darkInk)),
-    );
-    expect(best).toBeGreaterThanOrEqual(4.5);
-    // Nearest passing solid to the 60% mid is accent9 (57%, 4.60:1).
-    expect(token).toBe("$accent9");
+  it("returns the solid when no mix reaches the wash contrast", () => {
+    expect(resolveAccentTintedSurface({ solid: "#fafafa", paper: "#ffffff" })).toBe("#fafafa");
   });
 
-  it("returns the preferred token when anchors cannot be parsed", () => {
-    expect(
-      resolveAaSolidFill({
-        preferred: { token: "$accentBackground", value: darkAccent[9] },
-        solids: [],
-        paper: undefined,
-        ink: darkInk,
-      }),
-    ).toBe("$accentBackground");
+  it("returns undefined for missing or unparseable inputs", () => {
+    for (const invalid of [undefined, "var(--nope)"]) {
+      expect(resolveAccentTintedSurface({ solid: invalid, paper: "#ffffff" })).toBeUndefined();
+      expect(resolveAccentTintedSurface({ solid: "#634fc4", paper: invalid })).toBeUndefined();
+    }
   });
 });
 
@@ -186,7 +93,7 @@ describe("resolveLegibleInkOn (MPO-448)", () => {
   it("hands a muted title on the dark accent tint to the readable anchor (4.05:1)", () => {
     expect(
       resolveLegibleInkOn({
-        fill: darkAccent[0],
+        fill: "hsla(250, 50%, 35%, 1)",
         preferred: "#a09ba6",
         paper: darkPaper,
         ink: darkInk,

package/src/theme/readableColor.ts

@@ -10,27 +10,9 @@ import {
 } from "./colorRules";
 
 /**
- * Luminance-computed readable text/glyph colors (Axiom 15 OPTICS + Axiom 12
- * LEGIBLE FLOOR).
- *
- * Two catalog-wide contrast traps this module closes:
- *
- * 1. Text sitting ON an accent/solid FILL (`useReadableTextOn`). Components
- *    that paint a selected/active row, chip or avatar with `$accentBackground`
- *    (or any solid step) and then let the label inherit the scheme's `$color`
- *    render ink-on-accent (~2.6:1) or, worse, near-white-on-bright-tint
- *    (~1.2:1). The readable foreground is whichever scheme anchor
- *    (paper `$color1` / ink `$color12`) carries more contrast on the ACTUAL
- *    fill — never assumed.
- *
- * 2. Accent-hued text on the PAGE (`useAccentOnSurface`). The readable accent
- *    is the most chromatic step of the theme's own accent ramp that still
- *    clears AA (4.5:1) on both page surfaces — a mid accent in light, a pale
- *    accent in dark.
- *
- * Both read live theme values so they stay correct across schemes, tints and
- * custom accent palettes; they mirror the runtime pattern already used by the
- * Switch thumb, Toast and Calendar chip.
+ * Live-theme contrast helpers for text on solids and accent ink on surfaces.
+ * The theme build holds the accent solid to the text floor. Accent-intent
+ * surfaces use a wash; selected rows and segments use the neutral tier.
  */
 
 function resolveTokenValue(
@@ -43,10 +25,10 @@ function resolveTokenValue(
 }
 
 /**
- * Readable text/glyph color to sit ON `fill` (a token like "$accentBackground"
- * / "$color8", or an already-resolved color value — e.g. the step returned by
- * `useAccentTintedSurface`): the scheme's paper (`$color1`) or ink (`$color12`)
- * anchor, whichever contrasts more on the resolved fill, returned as a concrete
+ * Readable text/glyph color to sit ON `fill` (a token like "$color8" or a
+ * resolved value, such as the wash from `useAccentTintedSurface`): the
+ * scheme's paper (`$color1`) or ink (`$color12`) anchor, whichever contrasts
+ * more on the resolved fill, returned as a concrete
  * value so no nested sub-theme can flip it. When neither anchor clears AA on
  * the fill, the pole that does (`holdInkFloor`). Returns `undefined` when any
  * color fails to resolve/parse — callers keep their own default in that case.
@@ -153,168 +135,46 @@ export function useAccentOnSurface(): string {
   }, [c1, c2, ink, steps.join("|")]);
 }
 
-/**
- * Accent SURFACE tier of the accent ramp, mirrored by scheme — the fill for a
- * selected/current chip that must carry the accent language at SURFACE
- * strength rather than as a solid (LC-05: selection is accent; the ViewSwitcher
- * rider pins segmented-control strength at "tinted", not the solid an accent
- * CTA takes).
- *
- * The step is a declared ramp POSITION, the same way the neutral ramp declares
- * its tiers (surface `$color2`, UI background `$color3`-`$color5`, text
- * `$color11`-`$color12`): the accent ramp's surface end is its palest step in a
- * light scheme and its deepest in a dark one, so the chip reads as a tinted
- * surface on either page. Scheme polarity comes from the paper/ink ANCHORS,
- * never from a surface token — a tint re-ramps surfaces, and keying off one
- * made this pick drift a step per tint (measured: the chip slid from the pale
- * accent to the palest accent under a yellow tint).
- *
- * Returns `undefined` when the accent ramp is absent or unparseable (tint
- * sub-themes without an accent ramp) — callers keep their neutral default
- * rather than render an unthemed chip.
- */
-// Ramp positions (1-based) of the accent surface tier per scheme.
-const ACCENT_SURFACE_STEP_LIGHT = 11;
-const ACCENT_SURFACE_STEP_DARK = 1;
+const ACCENT_WASH_RATIO = 1.2;
 
 export interface ResolveAccentTintedSurfaceInput {
-  /** Accent ramp steps 1..12, as raw color values; holes allowed. */
-  steps: (string | undefined)[];
-  /** Scheme paper anchor (`$color1`). */
+  solid?: string;
   paper?: string;
-  /** Scheme ink anchor (`$color12`). */
-  ink?: string;
-}
-
-/** Pure resolver behind {@link useAccentTintedSurface} — see its docs. */
-export function resolveAccentTintedSurface({
-  steps,
-  paper,
-  ink,
-}: ResolveAccentTintedSurfaceInput): string | undefined {
-  const paperHex = paper ? normalizeToHex(paper) : null;
-  const inkHex = ink ? normalizeToHex(ink) : null;
-  if (!paperHex || !inkHex) return undefined;
-  const isLight = relativeLuminance(paperHex) > relativeLuminance(inkHex);
-  const step = steps[(isLight ? ACCENT_SURFACE_STEP_LIGHT : ACCENT_SURFACE_STEP_DARK) - 1];
-  if (!step || !normalizeToHex(step)) return undefined;
-  return step;
-}
-
-export function useAccentTintedSurface(): string | undefined {
-  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
-  const paper = resolveTokenValue(theme, "color1");
-  const ink = resolveTokenValue(theme, "color12");
-  const steps: (string | undefined)[] = [];
-  for (let i = 1; i <= 12; i++) steps.push(resolveTokenValue(theme, `accent${i}`));
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  return useMemo(
-    () => resolveAccentTintedSurface({ steps, paper, ink }),
-    [paper, ink, steps.join("|")],
-  );
 }
 
 /**
- * A named solid in the accent ramp. `token` is what a caller paints
- * (`$accentBackground`, `$accent9`); `value` is the resolved color.
+ * Accent wash for an accent-intent surface, mixed from the accent solid and
+ * paper. Selection uses the neutral tier in `componentColors.selection` or
+ * `formSelectionColors`, never this wash.
  */
-export interface AaSolidCandidate {
-  token: string;
-  value: string | undefined;
-}
-
-export interface ResolveAaSolidFillInput {
-  /** The LC-05 selected solid, usually `$accentBackground`. */
-  preferred: AaSolidCandidate;
-  /**
-   * Accent solids (steps 1–10). Pale anchors 11–12 are tinted surfaces, not
-   * selection solids — they would pass AA as chips and fail LC-05 as marks.
-   */
-  solids: AaSolidCandidate[];
-  paper?: string;
-  ink?: string;
-  /** Defaults to {@link aaTextContrastRatio} (4.5). */
-  floor?: number;
-}
-
-function bestAnchorContrast(fill: string, paperLum: number, inkLum: number): number {
-  const hex = normalizeToHex(fill);
-  if (!hex) return 0;
-  const fillLum = relativeLuminance(hex);
-  return Math.max(contrastRatio(fillLum, paperLum), contrastRatio(fillLum, inkLum));
-}
-
-/**
- * Pick an accent solid that can carry AA text (paper or ink ≥ 4.5).
- *
- * A mid-chroma solid can clear the graphic 3:1 tier and still miss the text
- * floor with both scheme anchors (the stock dark `#7766cc` measured 4.02:1
- * before the build held `$accentBackground` to it, MPO-448). Walking to the
- * nearest passing solid keeps the mark on the accent channel (LC-05) instead
- * of dropping to ink or a tinted surface.
- *
- * Returns the preferred token when it already clears the floor, otherwise
- * the solid token whose resolved luminance is closest to the preferred fill.
- */
-export function resolveAaSolidFill({
-  preferred,
-  solids,
+export function resolveAccentTintedSurface({
+  solid,
   paper,
-  ink,
-  floor = aaTextContrastRatio,
-}: ResolveAaSolidFillInput): string {
+}: ResolveAccentTintedSurfaceInput): string | undefined {
+  const solidHex = solid ? normalizeToHex(solid) : null;
   const paperHex = paper ? normalizeToHex(paper) : null;
-  const inkHex = ink ? normalizeToHex(ink) : null;
-  if (!paperHex || !inkHex) return preferred.token;
+  if (!solidHex || !paperHex) return undefined;
   const paperLum = relativeLuminance(paperHex);
-  const inkLum = relativeLuminance(inkHex);
-
-  if (preferred.value && bestAnchorContrast(preferred.value, paperLum, inkLum) >= floor) {
-    return preferred.token;
+  const solidRgb = [1, 3, 5].map((offset) => parseInt(solidHex.slice(offset, offset + 2), 16));
+  const paperRgb = [1, 3, 5].map((offset) => parseInt(paperHex.slice(offset, offset + 2), 16));
+  for (let step = 1; step <= 50; step++) {
+    const share = step * 0.02;
+    const mix = `#${paperRgb
+      .map((channel, index) =>
+        Math.round(channel + (solidRgb[index] - channel) * share)
+          .toString(16)
+          .padStart(2, "0"),
+      )
+      .join("")}`;
+    if (contrastRatio(relativeLuminance(mix), paperLum) >= ACCENT_WASH_RATIO) return mix;
   }
-
-  const preferredHex = preferred.value ? normalizeToHex(preferred.value) : null;
-  const preferredLum = preferredHex ? relativeLuminance(preferredHex) : undefined;
-  let bestToken: string | undefined;
-  let bestDist = Number.POSITIVE_INFINITY;
-  for (const { token, value } of solids) {
-    if (!value || bestAnchorContrast(value, paperLum, inkLum) < floor) continue;
-    const hex = normalizeToHex(value);
-    if (!hex) continue;
-    const dist = preferredLum === undefined ? 0 : Math.abs(relativeLuminance(hex) - preferredLum);
-    if (dist < bestDist) {
-      bestDist = dist;
-      bestToken = token;
-    }
-  }
-  return bestToken ?? preferred.token;
+  return solidHex;
 }
 
-/**
- * Token to paint as a selected/current solid so on-fill text clears AA.
- * See {@link resolveAaSolidFill}.
- */
-export function useAaSolidFill(preferredToken: string): string {
+/** Accent-intent wash; selection belongs to the shared neutral tier. */
+export function useAccentTintedSurface(): string | undefined {
   const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const solid = resolveTokenValue(theme, "accentBackground");
   const paper = resolveTokenValue(theme, "color1");
-  const ink = resolveTokenValue(theme, "color12");
-  const preferredValue = preferredToken.startsWith("$")
-    ? resolveTokenValue(theme, preferredToken)
-    : preferredToken;
-  const solids: AaSolidCandidate[] = [];
-  for (let i = 1; i <= 10; i++) {
-    solids.push({ token: `$accent${i}`, value: resolveTokenValue(theme, `accent${i}`) });
-  }
-  const solidsKey = solids.map((s) => s.value ?? "").join("|");
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  return useMemo(
-    () =>
-      resolveAaSolidFill({
-        preferred: { token: preferredToken, value: preferredValue },
-        solids,
-        paper,
-        ink,
-      }),
-    [preferredToken, preferredValue, paper, ink, solidsKey],
-  );
+  return useMemo(() => resolveAccentTintedSurface({ solid, paper }), [solid, paper]);
 }