@multiplatform.one/theme 7.4.1 → 7.6.0

package/src/theme/colorRules.spec.ts

@@ -1,13 +1,22 @@
 import { describe, expect, it } from "vitest";
 import {
-  normalizeToHex,
-  relativeLuminance,
+  aaTextContrastRatio,
+  assertContrast,
   contrastRatio,
   findReadableStep,
+  measureContrast,
+  minContrastRatio,
   normalizeColorScale,
+  normalizeToHex,
+  relativeLuminance,
+  resolveThemeContrast,
   $color,
   semanticGroups,
 } from "./colorRules";
+import { createThemesBuilder } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
 
 describe("normalizeToHex", () => {
   it('normalizes "white" to #ffffff', () => {
@@ -193,3 +202,298 @@ describe("semanticGroups", () => {
     expect(semanticGroups[semanticGroups.length - 1].to).toBe(12);
   });
 });
+
+describe("measureContrast", () => {
+  it("reports 21:1 for black on white and passes the AA floor", () => {
+    const report = measureContrast({ foreground: "#000000", background: "#ffffff" });
+    expect(report).toMatchObject({
+      foreground: "#000000",
+      background: "#ffffff",
+      ratio: 21,
+      floor: aaTextContrastRatio,
+      pass: true,
+    });
+  });
+
+  it("defaults the label to 'foreground on background'", () => {
+    expect(measureContrast({ foreground: "black", background: "white" }).label).toBe(
+      "black on white",
+    );
+  });
+
+  it("keeps a custom label and normalizes named/shorthand colors", () => {
+    const report = measureContrast({
+      foreground: "black",
+      background: "#fff",
+      label: "ink on paper",
+    });
+    expect(report.label).toBe("ink on paper");
+    expect(report.foreground).toBe("#000000");
+    expect(report.background).toBe("#ffffff");
+  });
+
+  it("fails the MPO-48 dark accent toast pill (1.94:1)", () => {
+    const report = measureContrast({
+      foreground: "#46349d",
+      background: "#161519",
+      label: "MPO-48 dark accent toast action",
+    });
+    expect(report.ratio).toBe(1.94);
+    expect(report.floor).toBe(aaTextContrastRatio);
+    expect(report.pass).toBe(false);
+  });
+
+  it("uses the reported 2-decimal ratio for the verdict", () => {
+    // #808080 on white is 3.9489…, reported 3.95 — pass at 3, miss at 4.5.
+    const at3 = measureContrast({
+      foreground: "#808080",
+      background: "#ffffff",
+      floor: minContrastRatio,
+    });
+    const atAa = measureContrast({ foreground: "#808080", background: "#ffffff" });
+    expect(at3.ratio).toBe(3.95);
+    expect(at3.pass).toBe(true);
+    expect(atAa.ratio).toBe(3.95);
+    expect(atAa.pass).toBe(false);
+  });
+
+  it("throws on an unparseable foreground — never a skip", () => {
+    expect(() => measureContrast({ foreground: "potato", background: "#ffffff" })).toThrow(
+      /foreground is not an opaque color: potato/,
+    );
+  });
+
+  it("throws on an alpha background — never a skip", () => {
+    expect(() =>
+      measureContrast({ foreground: "#000000", background: "hsla(0, 0%, 100%, 0.2)" }),
+    ).toThrow(/background is not an opaque color/);
+  });
+});
+
+describe("assertContrast", () => {
+  it("returns the reports when every pair clears its floor", () => {
+    const reports = assertContrast({ foreground: "black", background: "white" });
+    expect(reports).toHaveLength(1);
+    expect(reports[0].pass).toBe(true);
+    expect(reports[0].ratio).toBe(21);
+  });
+
+  it("throws ONE error naming every miss, not the first", () => {
+    expect(() =>
+      assertContrast([
+        { foreground: "black", background: "white", label: "ok" },
+        { foreground: "#46349d", background: "#161519", label: "toast pill" },
+        { foreground: "#808080", background: "#ffffff", label: "gray" },
+      ]),
+    ).toThrow(
+      /contrast floor missed \(2 of 3 pairs\):[\s\S]*toast pill: #46349d on #161519 = 1.94:1[\s\S]*gray: #808080 on #ffffff = 3.95:1/,
+    );
+  });
+});
+
+describe("resolveThemeContrast", () => {
+  it("addresses a pair by theme name and keys", () => {
+    expect(
+      resolveThemeContrast(
+        { light: { color: "#242226", background: "#ffffff" } },
+        { theme: "light", foreground: "color", background: "background" },
+      ),
+    ).toEqual({
+      foreground: "#242226",
+      background: "#ffffff",
+      floor: undefined,
+      label: "light: color on background",
+    });
+  });
+
+  it("carries an optional floor through to the pair", () => {
+    expect(
+      resolveThemeContrast(
+        { light: { color: "#fff", background: "#000" } },
+        { theme: "light", foreground: "color", background: "background", floor: minContrastRatio },
+      ).floor,
+    ).toBe(minContrastRatio);
+  });
+
+  it("throws on a missing theme rather than skipping", () => {
+    expect(() =>
+      resolveThemeContrast({}, { theme: "nope", foreground: "color", background: "background" }),
+    ).toThrow("no such theme: nope");
+  });
+
+  it("throws on a missing key rather than skipping", () => {
+    expect(() =>
+      resolveThemeContrast(
+        { light: { color: "#000" } },
+        { theme: "light", foreground: "color", background: "background" },
+      ),
+    ).toThrow("light has no background");
+  });
+});
+
+describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
+  const themes = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes() as Record<string, Record<string, string>>;
+
+  it("base text tiers clear AA on page surfaces in both schemes", () => {
+    const pairs = [];
+    for (const scheme of ["light", "dark"] as const) {
+      for (const foreground of ["color", "color11", "color12"]) {
+        for (const background of ["background", "color1", "color2"]) {
+          pairs.push(resolveThemeContrast(themes, { theme: scheme, foreground, background }));
+        }
+      }
+    }
+    const reports = assertContrast(pairs);
+    expect(reports.every((report) => report.pass)).toBe(true);
+    expect(reports).toHaveLength(18);
+  });
+
+  it("accent Button color-on-background clears AA in both schemes", () => {
+    const reports = assertContrast(
+      (["light_accent_Button", "dark_accent_Button"] as const).map((theme) =>
+        resolveThemeContrast(themes, { theme, foreground: "color", background: "background" }),
+      ),
+    );
+    expect(reports.map((report) => report.ratio)).toEqual([7.31, 7.61]);
+  });
+
+  it("a colour pair below the floor FAILS", () => {
+    // MPO-48 measured the dark accent toast action pill on the page ground.
+    // Built: dark_accent.backgroundHover is #46349d; dark.background is #161519.
+    expect(() =>
+      assertContrast({
+        foreground: themes.dark_accent.backgroundHover,
+        background: themes.dark.background,
+        label: "MPO-48 dark accent toast action",
+      }),
+    ).toThrow(/MPO-48 dark accent toast action: #46349d on #161519 = 1.94:1/);
+
+    // MPO-40: outlined warning $color11 on the warning page surface is 4.44:1.
+    expect(() =>
+      assertContrast(
+        resolveThemeContrast(themes, {
+          theme: "light_warning",
+          foreground: "color11",
+          background: "color1",
+        }),
+      ),
+    ).toThrow(/light_warning: color11 on color1: #9e6c00 on #fcfcf7 = 4.44:1/);
+  });
+
+  it("current light_accent color-on-background clears the 3:1 non-text floor", () => {
+    // Parent accent is 3.96:1 — under AA, over the large-text/UI floor. The
+    // Button pair (asserted above) is the AA text contract; this pair is the
+    // trip-wire's control so the old pale-lavender step is the thing that fails.
+    const reports = assertContrast(
+      resolveThemeContrast(themes, {
+        theme: "light_accent",
+        foreground: "color",
+        background: "background",
+        floor: minContrastRatio,
+      }),
+    );
+    expect(reports[0].ratio).toBe(3.96);
+    expect(reports[0].pass).toBe(true);
+  });
+
+  it("re-introducing the old accent lightPalette[0] fails the test", () => {
+    // The pale-lavender step that shipped a ~1.17:1 CTA. Swapping only [0]
+    // leaves Button (palette[3]) alone and drops light_accent.background.
+    const broken = createThemesBuilder(
+      defaultBaseTheme,
+      {
+        ...defaultAccentTheme,
+        lightPalette: ["hsla(250, 50%, 95%, 1)", ...defaultAccentTheme.lightPalette.slice(1)],
+      },
+      defaultBuilderOptions,
+    ).themes() as Record<string, Record<string, string>>;
+
+    expect(() =>
+      assertContrast(
+        resolveThemeContrast(broken, {
+          theme: "light_accent",
+          foreground: "color",
+          background: "background",
+          floor: minContrastRatio,
+        }),
+      ),
+    ).toThrow(/light_accent: color on background: #f9f8fc on #eeecf9 = 1.1:1/);
+  });
+});
+
+describe("intent color11 on the base page surfaces (MPO-40)", () => {
+  const themes = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes() as Record<string, Record<string, string>>;
+
+  const schemes = ["light", "dark"] as const;
+  const intents = ["error", "warning", "success"] as const;
+  // The surfaces an outlined control's TRANSPARENT frame can sit on. The
+  // intent sub-theme supplies the ink; the page behind it supplies the
+  // ground, so the pair is cross-theme and `resolveThemeContrast` (one
+  // theme) cannot address it.
+  const surfaces = ["background", "color1", "color2"] as const;
+
+  const intentInkPairs = schemes.flatMap((scheme) =>
+    intents.flatMap((intent) =>
+      surfaces.map((surface) => ({
+        foreground: themes[`${scheme}_${intent}`].color11,
+        background: themes[scheme][surface],
+        label: `${scheme}_${intent}: color11 on ${scheme}.${surface}`,
+      })),
+    ),
+  );
+
+  /**
+   * MPO-40 measured the outlined intent label on the gallery harness ground
+   * and recorded warning 4.34:1 and success 4.48:1. That ground is the BASE
+   * theme's `color2` (#f9f9fa) — NOT `background`/`color1`, which are both
+   * #ffffff and where the same two pairs clear the floor at 4.57 and 4.72.
+   * The miss is therefore surface-specific: an outlined warning or success
+   * Button only goes unreadable once it sits on a color2 surface (a card, a
+   * striped row, the gallery ground). Measuring against the plain page is
+   * exactly how a check reports a pass on a control that is failing.
+   *
+   * The two misses are PINNED to their measured ratios rather than skipped.
+   * Raise the $color11 step and the recorded ratio stops matching, which
+   * fails here and forces the entry out of this table — an exemption that
+   * retires itself instead of one that rots.
+   */
+  const pinnedMisses: Record<string, number> = {
+    "light_warning: color11 on light.color2": 4.34,
+    "light_success: color11 on light.color2": 4.48,
+  };
+
+  it("sweeps every intent x base surface x scheme — 18 pairs, none dropped", () => {
+    expect(intentInkPairs).toHaveLength(18);
+  });
+
+  it("clears AA everywhere except the two pinned MPO-40 misses", () => {
+    const misses = intentInkPairs
+      .map(measureContrast)
+      .filter((report) => !report.pass)
+      .map((report) => [report.label, report.ratio] as const);
+    expect(Object.fromEntries(misses)).toEqual(pinnedMisses);
+  });
+
+  it("the same warning/success ink clears the floor on background and color1", () => {
+    // Locks the surface-specificity so a future fix cannot be signed off by
+    // re-measuring against the white page.
+    const reports = assertContrast(
+      (["warning", "success"] as const).flatMap((intent) =>
+        (["background", "color1"] as const).map((surface) => ({
+          foreground: themes[`light_${intent}`].color11,
+          background: themes.light[surface],
+          label: `light_${intent}: color11 on light.${surface}`,
+        })),
+      ),
+    );
+    expect(reports.map((report) => report.ratio)).toEqual([4.57, 4.57, 4.72, 4.72]);
+  });
+});

package/src/theme/colorRules.ts

@@ -77,6 +77,124 @@ export const minContrastRatio = 3;
 /** WCAG AA contrast floor for normal-size body/label text. */
 export const aaTextContrastRatio = 4.5;
 
+// ── Contrast floor assertion (DG-A11Y-01 / DG-COL-01) ─────────
+//
+// `aaTextContrastRatio` declared a floor that no code enforced: MPO-40's
+// outlined warning $color11 (#9e6c00, 4.34:1) and success (#218358, 4.48:1)
+// and MPO-48's dark accent toast action pill (#46349d on #161519, 1.94:1)
+// all shipped through review, tests and a design pass. This is THE one
+// enforcement — theme specs here, shc's contrast.spec.ts and MPO-18's
+// theme matrix all call it instead of re-deriving the arithmetic.
+
+/** A foreground/background pair held to a WCAG contrast floor. */
+export interface ContrastPair {
+  /** Text/glyph color, in any format `normalizeToHex` accepts. */
+  foreground: string;
+  /** The fill the foreground sits on. */
+  background: string;
+  /** Floor the pair owes. Defaults to `aaTextContrastRatio` (4.5). */
+  floor?: number;
+  /** Names the pair in reports, e.g. "light_accent: color on background". */
+  label?: string;
+}
+
+/** Measured outcome for one {@link ContrastPair}. */
+export interface ContrastReport {
+  label: string;
+  /** The colors actually measured, as normalized 6-digit hex. */
+  foreground: string;
+  background: string;
+  /** WCAG 2.x ratio rounded to 2 decimals — the number a report reads. */
+  ratio: number;
+  floor: number;
+  pass: boolean;
+}
+
+/**
+ * Measure one pair against its floor. Throws when a color cannot be reduced
+ * to an opaque hex: an alpha color has no contrast of its own and the house
+ * ramps are fully opaque, so an unmeasurable pair is a genuine failure,
+ * never a skip. The verdict compares the REPORTED (2-decimal) ratio, so
+ * pass/fail always matches the printed number.
+ */
+export function measureContrast(pair: ContrastPair): ContrastReport {
+  const floor = pair.floor ?? aaTextContrastRatio;
+  const label = pair.label ?? `${pair.foreground} on ${pair.background}`;
+  const foreground = normalizeToHex(pair.foreground);
+  if (!foreground) {
+    throw new Error(`${label}: foreground is not an opaque color: ${pair.foreground}`);
+  }
+  const background = normalizeToHex(pair.background);
+  if (!background) {
+    throw new Error(`${label}: background is not an opaque color: ${pair.background}`);
+  }
+  const ratio =
+    Math.round(contrastRatio(relativeLuminance(foreground), relativeLuminance(background)) * 100) /
+    100;
+  return { label, foreground, background, ratio, floor, pass: ratio >= floor };
+}
+
+/**
+ * The contrast floor assertion. Measures every pair and throws ONE error
+ * naming every pair under its floor — a sweep reports the whole damage, not
+ * the first miss. Returns the reports when all pass, so callers can attach
+ * the measured numbers as proof.
+ */
+export function assertContrast(pairs: ContrastPair | ContrastPair[]): ContrastReport[] {
+  const reports = (Array.isArray(pairs) ? pairs : [pairs]).map(measureContrast);
+  const misses = reports.filter((report) => !report.pass);
+  if (misses.length > 0) {
+    const lines = misses.map(
+      (report) =>
+        `${report.label}: ${report.foreground} on ${report.background} = ` +
+        `${report.ratio}:1 — under the ${report.floor}:1 floor`,
+    );
+    throw new Error(
+      `contrast floor missed (${misses.length} of ${reports.length} pairs):\n${lines.join("\n")}`,
+    );
+  }
+  return reports;
+}
+
+/** Addresses a {@link ContrastPair} inside built themes by name and keys. */
+export interface ThemeContrastPair {
+  /** Theme name, e.g. "light_accent" or "dark". */
+  theme: string;
+  /** Theme key carrying the text/glyph color, e.g. "color" or "color11". */
+  foreground: string;
+  /** Theme key carrying the fill, e.g. "background" or "color2". */
+  background: string;
+  /** Floor the pair owes. Defaults to `aaTextContrastRatio` (4.5). */
+  floor?: number;
+}
+
+/**
+ * Resolve a pair out of BUILT themes — the record `createThemesBuilder`
+ * returns, the same objects handed to createTamagui. Asserting on built
+ * themes rather than source ramps is the point: the pairing that fails is
+ * produced layers away by the theme-builder template, so reading a palette
+ * file tells you nothing about what lands under a label. Addressed by theme
+ * name + key so a failure names the thing a designer would change; a missing
+ * theme or key throws rather than skips.
+ */
+export function resolveThemeContrast(
+  themes: Record<string, Record<string, string> | undefined>,
+  pair: ThemeContrastPair,
+): ContrastPair {
+  const theme = themes[pair.theme];
+  if (!theme) throw new Error(`no such theme: ${pair.theme}`);
+  const foreground = theme[pair.foreground];
+  if (!foreground) throw new Error(`${pair.theme} has no ${pair.foreground}`);
+  const background = theme[pair.background];
+  if (!background) throw new Error(`${pair.theme} has no ${pair.background}`);
+  return {
+    foreground,
+    background,
+    floor: pair.floor,
+    label: `${pair.theme}: ${pair.foreground} on ${pair.background}`,
+  };
+}
+
 /**
  * Axiom 15 OPTICS — pick whichever candidate foreground carries more WCAG
  * contrast on a given `fill`. The canonical "readable foreground on a fill"

package/src/theme/cornerSmoothing.native.ts

@@ -2,15 +2,52 @@
  * OPTICS corner smoothing (Axiom 15) — native twin of `cornerSmoothing.ts`.
  *
  * React Native has no `corner-shape`; native resolves `cornerSmoothing` to
- * `round` (resolveKnobs emits no class on native) until a SquircleView
- * adoption lands (phase 2). Exports stay shape-compatible for shared code.
+ * `round` until a SquircleView adoption lands (phase 2). Exports stay
+ * shape-compatible so shared code and tests can import either file.
  */
+import type { CornerSmoothing } from "./knobs";
 
 /** Class attached on web only — never emitted into native fragments. */
 export const cornerSmoothClassName = "mp-corner-smooth";
 
+export const CORNER_SMOOTHING_STYLE_TAG_ID = "mp-corner-smoothing-styles";
+export const CORNER_SMOOTHING_ROOT_ATTR = "data-mp-corner-smoothing";
+export const CORNER_SHAPE_CSS_VAR = "--mp-corner-shape";
+export const CORNER_SHAPE_ROUND = "round";
+export const CORNER_SHAPE_SMOOTH = "squircle";
+export const CORNER_SHAPE_ROUND_COMPUTED = "superellipse(1)";
+export const CORNER_SHAPE_SMOOTH_COMPUTED = "superellipse(2)";
+
 /** Web-only stylesheet — empty on native. */
 export const cornerSmoothingCss = "";
 
+/** Native has no CSS.supports corner-shape — measured no-op, not assumed. */
+export function cssSupportsCornerShape(_supports?: {
+  supports?(property: string, value: string): boolean;
+}): boolean {
+  return false;
+}
+
+export function readComputedCornerShape(
+  _style?: Pick<CSSStyleDeclaration, "getPropertyValue"> & { cornerShape?: string },
+): string {
+  return "";
+}
+
+export function isSmoothComputedCornerShape(_value: string): boolean {
+  return false;
+}
+
+export function isRoundComputedCornerShape(_value: string): boolean {
+  return true;
+}
+
+export function applyRootCornerSmoothing(_stop?: CornerSmoothing): void {}
+
 /** Web-only stylesheet mount — no-op on native. */
 export function ensureCornerSmoothingStyles(): void {}
+
+/** Native no-op. Web mounts the squircle stylesheet from ThemeProvider. */
+export function CornerSmoothingStyles(): null {
+  return null;
+}