@multiplatform.one/theme 8.3.0 → 8.4.0

package/src/theme/controlEdges.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import { createThemesBuilder } from "./createThemes";
+import { resolveThemeThroughParents } from "./dedupeInherited";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+
+const themes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+
+const intents = new Set(["error", "warning", "success"]);
+
+function ratio(a: string | undefined, b: string | undefined) {
+  const aHex = normalizeToHex(a ?? "");
+  const bHex = normalizeToHex(b ?? "");
+  if (!aHex || !bHex) throw new Error(`Expected opaque colours: ${a}, ${b}`);
+  return contrastRatio(relativeLuminance(aHex), relativeLuminance(bHex));
+}
+
+const resolve = (name: string) =>
+  resolveThemeThroughParents(themes, name) as unknown as Record<string, string>;
+
+const scopes = Object.keys(themes).filter(
+  (name) => /^(light|dark)(_[a-z]+)?$/.test(name) && !/_(accent|active)$/.test(name),
+);
+const hueScopes = scopes.filter((name) => !intents.has(name.split("_")[1] ?? ""));
+const intentScopes = scopes.filter((name) => intents.has(name.split("_")[1] ?? ""));
+
+describe("LC-299 CONTROL-EDGE: control edges clear WCAG 1.4.11's 3:1", () => {
+  it("covers both schemes and every preset hue", () => {
+    for (const hue of ["blue", "purple", "green", "orange", "pink"]) {
+      expect(hueScopes).toContain(`light_${hue}`);
+      expect(hueScopes).toContain(`dark_${hue}`);
+    }
+  });
+
+  for (const scope of hueScopes) {
+    it(`${scope}: field edges hold 3:1 on the page and on their own fill`, () => {
+      const page = resolve(scope);
+      for (const control of ["Input", "TextArea", "SelectTrigger", "InputContainerFrame"]) {
+        const field = resolve(`${scope}_${control}`);
+        for (const key of ["borderColorField", "borderColorFieldHover"]) {
+          expect(
+            ratio(field[key], page.background),
+            `${control} ${key} on page`,
+          ).toBeGreaterThanOrEqual(minContrastRatio);
+          expect(
+            ratio(field[key], field.background),
+            `${control} ${key} on its fill`,
+          ).toBeGreaterThanOrEqual(minContrastRatio);
+        }
+      }
+    });
+
+    it(`${scope}: the segmented frame edge holds 3:1 on the page`, () => {
+      const page = resolve(scope);
+      expect(ratio(page.borderColorControl, page.background)).toBeGreaterThanOrEqual(
+        minContrastRatio,
+      );
+    });
+
+    it(`${scope}: the off Switch track edge`, () => {
+      const page = resolve(scope);
+      const track = resolve(`${scope}_Switch`);
+      if (scope.startsWith("light")) {
+        expect(ratio(track.switchTrackOffBorder, page.background)).toBeGreaterThanOrEqual(
+          minContrastRatio,
+        );
+      } else {
+        expect(track.switchTrackOffBorder).toBe(track.switchTrackOff);
+      }
+    });
+  }
+
+  for (const scope of intentScopes) {
+    it(`${scope}: an intent field edge comes from its own ramp and holds 3:1`, () => {
+      const scheme = scope.split("_")[0]!;
+      const own = Array.from({ length: 12 }, (_, index) => themes[scope]![`color${index + 1}`]);
+      const pages = hueScopes.filter((name) => name.startsWith(`${scheme}_`)).concat(scheme);
+      for (const control of ["Input", "TextArea", "SelectTrigger", "InputContainerFrame"]) {
+        const field = resolve(`${scope}_${control}`);
+        for (const key of ["borderColorField", "borderColorFieldHover"]) {
+          expect(own, `${control} ${key}`).toContain(field[key]);
+          for (const page of pages)
+            expect(
+              ratio(field[key], resolve(page).background),
+              `${control} ${key} on ${page}`,
+            ).toBeGreaterThanOrEqual(minContrastRatio);
+          expect(
+            ratio(field[key], field.background),
+            `${control} ${key} on its fill`,
+          ).toBeGreaterThanOrEqual(minContrastRatio);
+        }
+      }
+    });
+  }
+
+  it("picks a neutral edge, not a tint that reads as the accent", () => {
+    for (const scope of hueScopes) {
+      const scheme = scope.split("_")[0]!;
+      const neutral = Array.from(
+        { length: 12 },
+        (_, index) => themes[scheme]![`color${index + 1}`],
+      );
+      const page = resolve(scope);
+      expect(neutral, `${scope} field`).toContain(page.borderColorField);
+      expect(neutral, `${scope} control`).toContain(page.borderColorControl);
+    }
+  });
+});

package/src/theme/controlTiers.ts

@@ -4,11 +4,11 @@
  *
  * - `tinted`, in content: a filled wash with no edge, the preset's radius and
  *   the size token's height. Light washes at `$color3` (#ededed on the stock
- *   ramp), dark one step further up at `$color4`, because dark `$color3` sits
- *   a single lightness point off the page and the button would vanish. On an
- *   elevated ground (`useElevatedSurface()`: an overlay frame or an unnested
- *   Panel) dark climbs one more step to `$color5`, because the dark elevated
- *   tint is `$color4` itself (HIG: a control's fill sits above the elevated
+ *   ramp), dark at `$color5`, one step above the `$color4` card and field it
+ *   usually sits in (LC-151, FZ-8400). On an elevated ground
+ *   (`useElevatedSurface()`: an overlay frame or an unnested Panel) dark
+ *   climbs one more step to `$color6`, because the dark elevated tint is
+ *   `$color5` itself (HIG: a control's fill sits above the elevated
  *   background it is on). Light's elevated ground is the page step, so its
  *   wash stays put.
  * - `plain`, inside a bar (`useBarSurface()`): ink only at rest, the tinted
@@ -30,11 +30,11 @@ export interface ControlTierPaint {
 }
 
 const lightWash: ControlTierPaint = { rest: "$color3", hover: "$color4", press: "$color5" };
-const darkWash: ControlTierPaint = { rest: "$color4", hover: "$color5", press: "$color6" };
+const darkWash: ControlTierPaint = { rest: "$color5", hover: "$color6", press: "$color7" };
 const darkElevatedWash: ControlTierPaint = {
-  rest: "$color5",
-  hover: "$color6",
-  press: "$color7",
+  rest: "$color6",
+  hover: "$color7",
+  press: "$color8",
 };
 
 /** The tinted wash for a scheme and ground: rest, hover and press fills. */
@@ -43,6 +43,15 @@ export function controlTierWash(dark: boolean, elevated = false): ControlTierPai
   return elevated ? darkElevatedWash : darkWash;
 }
 
+/**
+ * A Slider or Progress track: `$color5`, a step above a dark `$color4` card;
+ * on a dark elevated ground `$color6`, a step above the `$color5` overlay
+ * (FZ-7944, FZ-8400). Light keeps `$color5`.
+ */
+export function controlTrackFill(dark: boolean, elevated = false): string {
+  return dark && elevated ? "$color6" : "$color5";
+}
+
 /** Rest, hover and press fills for a tier in a scheme, on the page or an elevated ground. */
 export function controlTierPaint(
   tier: ControlTier,

package/src/theme/createDefaultThemeConfig.spec.ts

@@ -36,6 +36,7 @@ import { createTamagui } from "tamagui";
 import { boldPreset, densePreset, heroPreset, roomyPreset } from "./presets";
 import { createThemesBuilder, type GetThemeProps } from "./createThemes";
 import { defaultBaseTheme, defaultAccentTheme } from "./defaults";
+import { darkHairlineContrast } from "./defaults/builderOptions";
 import { setSizeRecipeInputs } from "./sizeRecipes";
 import { resolveThemeThroughParents } from "./dedupeInherited";
 
@@ -157,8 +158,9 @@ describe("createDefaultThemeConfig — builderOptions.getTheme composition (DF-0
     for (const scheme of ["light", "dark"] as const) {
       const theme = themes[scheme];
       expect(normalizeToHex(theme.outlineColor)).toBeTruthy();
-      // LC-152: textMuted is the secondary ink, $color9 in light, $color10 in dark.
-      expect(theme.textMuted).toBe(theme[scheme === "light" ? "color9" : "color10"]);
+      // LC-152: textMuted is the secondary ink, $color9 in light and, on the
+      // dark $color4 card (FZ-8400), $color11 in dark.
+      expect(theme.textMuted).toBe(theme[scheme === "light" ? "color9" : "color11"]);
     }
     expect(config.recipeFamilies?.control.boxVariants.$4.height).toBe(40);
   });
@@ -333,9 +335,10 @@ describe("the v5 theme matrix", () => {
   const themes = config.tamagui.themes as unknown as RawThemes;
 
   // LC-151 SURFACE-LADDER: the grouped step. Light lifts cards, list items
-  // and fields to white on the grey page; dark keeps them one step lighter
-  // than the page (the LC-85 pair). The grouped step is light surface1 itself,
-  // so it costs no CSS; tracks move to surface2 to stay off a white card.
+  // and fields to white on the grey page; dark drops the page to $color1 and
+  // lifts them to $color4, iOS's grouped step (FZ-8400). The grouped step is
+  // surface1 itself, so it costs no CSS; tracks move to surface2 to stay off
+  // a white card.
   it("puts cards, list items and fields on the grouped step", () => {
     for (const component of [
       "Card",
@@ -349,7 +352,7 @@ describe("the v5 theme matrix", () => {
       expect(themes[`light_${component}`].background, `light_${component}`).toBe(
         themes.light.color1,
       );
-      expect(themes[`dark_${component}`].background, `dark_${component}`).toBe(themes.dark.color3);
+      expect(themes[`dark_${component}`].background, `dark_${component}`).toBe(themes.dark.color4);
       expect(themes[`light_${component}`].backgroundPress, `light_${component} press`).toBe(
         themes.light.color3,
       );
@@ -364,6 +367,123 @@ describe("the v5 theme matrix", () => {
     expect(themes.light_orange_Card.background).toBe(themes.light_orange.color1);
   });
 
+  const edgeSurfaces = ["_Card", "_ListItem", "_Input", "_TextArea", "_SelectTrigger"];
+
+  // FZ-9281 / LC-148: iOS's dark opaqueSeparator #38383A over its grouped cell
+  // #1C1C1E is 1.454:1. Every dark ramp theme's hairline clears that against
+  // the page and against the grouped surface (a Card) it divides.
+  it("lifts every dark hairline off the page and the card by iOS's separator step", () => {
+    const iosSeparatorStep = contrastRatio(
+      relativeLuminance("#38383a"),
+      relativeLuminance("#1c1c1e"),
+    );
+    expect(darkHairlineContrast).toBeCloseTo(iosSeparatorStep, 2);
+    const hex = (value: unknown) =>
+      normalizeToHex(String(typeof value === "string" ? value : (value as { val?: string })?.val))!;
+    const contrastOf = (a: unknown, b: unknown) =>
+      contrastRatio(relativeLuminance(hex(a)), relativeLuminance(hex(b)));
+    const names = Object.keys(themes).filter((name) => /^dark(_[a-z]+)?$/.test(name));
+    expect(names.length).toBeGreaterThan(8);
+    const luminanceOf = (value: unknown) => relativeLuminance(hex(value));
+    for (const name of names) {
+      if (name === "dark_active" || name === "dark_accent") continue;
+      const page = resolveThemeThroughParents(themes, name);
+      for (const surface of ["", ...edgeSurfaces]) {
+        const theme = resolveThemeThroughParents(themes, `${name}${surface}`);
+        const label = `${name}${surface}`;
+        const grounds = surface ? [page.background, theme.background] : [page.background];
+        for (const ground of grounds) {
+          expect(
+            contrastOf(theme.borderColorHairline, ground),
+            `${label} hairline on ${ground === page.background ? "page" : "surface"}`,
+          ).toBeGreaterThanOrEqual(iosSeparatorStep);
+        }
+        for (const ground of grounds) {
+          expect(
+            contrastOf(theme.borderColor, ground),
+            `${label} medium edge on ${ground === page.background ? "page" : "surface"}`,
+          ).toBeGreaterThanOrEqual(iosSeparatorStep);
+        }
+        expect(luminanceOf(theme.borderColor), `${label} medium above hairline`).toBeGreaterThan(
+          luminanceOf(theme.borderColorHairline),
+        );
+      }
+    }
+  });
+
+  it("keeps every light edge where it was (FZ-9281 is dark only)", () => {
+    const value = (raw: unknown) =>
+      String(typeof raw === "string" ? raw : (raw as { val?: string })?.val);
+    const edges = Object.keys(themes)
+      .filter((name) => /^light(_[a-z]+)?$/.test(name))
+      .sort()
+      .flatMap((name) =>
+        ["", ...edgeSurfaces].map((surface) => {
+          const theme = resolveThemeThroughParents(themes, `${name}${surface}`);
+          return `${name}${surface} ${value(theme.borderColorHairline)} ${value(theme.borderColor)}`;
+        }),
+      );
+    expect(edges.join("\n")).toMatchSnapshot();
+  });
+
+  // FZ-8400: iOS's grouped step is secondarySystemGroupedBackground #1C1C1E
+  // on systemGroupedBackground #000000, 1.23:1. Every preset's dark page and
+  // its inset group (a Card) clear it, the group's own small edge reads off
+  // its fill, and a Button and an overlay still step off the card.
+  it("steps dark grouped surfaces off the page by at least iOS's grouped step", () => {
+    const iosGroupedStep = contrastRatio(
+      relativeLuminance("#1c1c1e"),
+      relativeLuminance("#000000"),
+    );
+    const contrastOf = (a: string, b: string) =>
+      contrastRatio(relativeLuminance(normalizeToHex(a)!), relativeLuminance(normalizeToHex(b)!));
+    const read = (name: string) => resolveThemeThroughParents(themes, name);
+    // The neutral ramp, the built-in presets' hues and the app presets' hues.
+    const presetHues = [boldPreset, heroPreset, densePreset, roomyPreset].map((p) => p.theme);
+    for (const hue of new Set([
+      "",
+      ...presetHues,
+      "blue",
+      "gray",
+      "purple",
+      "green",
+      "orange",
+      "pink",
+    ])) {
+      const at = (suffix: string) => read(["dark", hue, suffix].filter(Boolean).join("_"));
+      const page = at("");
+      const card = at("Card");
+      const label = hue || "neutral";
+      expect(
+        contrastOf(card.background, page.background),
+        `${label} card on page`,
+      ).toBeGreaterThanOrEqual(iosGroupedStep);
+      expect(
+        relativeLuminance(normalizeToHex(at("Button").background)!),
+        `${label} button over card`,
+      ).toBeGreaterThan(relativeLuminance(normalizeToHex(card.background)!));
+      // LC-05 selection fills inside the group never land on its own fill,
+      // and on the page they stay the ramp steps they replaced.
+      for (const key of ["selectFill", "selectPress"]) {
+        expect(contrastOf(card[key], card.background), `${label} ${key} on card`).toBeGreaterThan(
+          1.1,
+        );
+      }
+      expect(page.selectFill, `${label} page selectFill`).toBe(page.color4);
+      expect(page.selectPress, `${label} page selectPress`).toBe(page.color5);
+    }
+    for (const scheme of ["light", "dark"] as const) {
+      for (const name of [scheme, `${scheme}_blue`, `${scheme}_gray`]) {
+        const page = themes[name];
+        expect([page.selectFill, page.selectPress], name).toEqual([page.color4, page.color5]);
+      }
+    }
+    expect(read("light_Card").selectFill).toBe(themes.light.color4);
+    // Light keeps the grey page and the white grouped step.
+    expect(themes.light.background).toBe(themes.light.color2);
+    expect(themes.light_Card.background).toBe(themes.light.color1);
+  });
+
   it("binds the v5 shadow3 alpha in both schemes", () => {
     for (const [scheme, alphas] of [
       ["light", [0.04, 0.08, 0.12, 0.22, 0.33, 0.44]],
@@ -377,9 +497,9 @@ describe("the v5 theme matrix", () => {
   });
 
   it("uses v5 surface templates for pages and components", () => {
-    for (const scheme of ["light", "dark"] as const) {
-      expect(themes[scheme].background).toBe(themes[scheme].color2);
-    }
+    expect(themes.light.background).toBe(themes.light.color2);
+    // FZ-8400: the dark page is the ramp's darkest step, iOS's black ground.
+    expect(themes.dark.background).toBe(themes.dark.color1);
     const button = themes.light_Button;
     expect(relativeLuminance(normalizeToHex(button.backgroundHover)!)).toBeGreaterThan(
       relativeLuminance(normalizeToHex(button.background)!),
@@ -415,10 +535,13 @@ describe("the v5 theme matrix", () => {
       builderOptions: { componentThemes: { Custom: { template: "surface1" } } },
     }).tamagui.themes as unknown as RawThemes;
     for (const scheme of ["light", "dark"] as const) {
-      expect(custom[`${scheme}_brand`].background).toBe(custom[`${scheme}_brand`].color2);
-      // surface1 is the LC-151 grouped step: white in light, one step up in dark.
+      // The page is $color2 in light and $color1 in dark (LC-151, FZ-8400).
+      expect(custom[`${scheme}_brand`].background).toBe(
+        custom[`${scheme}_brand`][scheme === "light" ? "color2" : "color1"],
+      );
+      // surface1 is the LC-151 grouped step: white in light, $color4 in dark.
       expect(custom[`${scheme}_Custom`].background).toBe(
-        custom[scheme][scheme === "light" ? "color1" : "color3"],
+        custom[scheme][scheme === "light" ? "color1" : "color4"],
       );
       expect(custom).not.toHaveProperty(`${scheme}_Button`);
     }