@multiplatform.one/theme 7.4.0 → 7.5.0

package/README.md

@@ -22,7 +22,8 @@ Requires `react` and `tamagui` as peers.
   including intent + component overrides
 - **Recipes** — control/text/elevation state recipes (hover, press, focus-visible)
 - **Optics** — the `cornerSmoothing` knob (`round` | `smooth` squircle corners:
-  web progressive enhancement via CSS `corner-shape`, native stays round),
+  web progressive enhancement via CSS `corner-shape: squircle`, computed
+  `superellipse(2)` on Chromium 152; native stays round),
   `hairline` separator treatments (0.5 device-pixel rules with a 1px low-DPI
   fallback), and tracking-by-size in the default font faces
 - **Chart palette** — `useChartPalette()`: identity-led series colors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.7.6",
     "@tamagui/web": "2.7.6",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/platform": "7.4.0",
-    "@multiplatform.one/store": "7.4.0"
+    "@multiplatform.one/platform": "7.5.0",
+    "@multiplatform.one/store": "7.5.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.7.6",
@@ -69,8 +69,8 @@
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.4.0",
-    "@multiplatform.one/test-utils": "7.4.0"
+    "@multiplatform.one/test-utils": "7.5.0",
+    "@multiplatform.one/config": "7.5.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/figma/figmaTokens.spec.ts

@@ -1,5 +1,5 @@
 import * as Colors from "@tamagui/colors";
-import { tokens } from "@tamagui/themes";
+import { defaultConfig } from "@tamagui/config/v5";
 import { describe, expect, it } from "vitest";
 import { normalizeToHex } from "../theme/colorRules";
 import { defaultAccentTheme } from "../theme/defaults/accent";
@@ -89,13 +89,13 @@ describe("buildFigmaTokens", () => {
 
   describe("semantic", () => {
     it("derives the current interaction-ramp aliases (post-knobs rebuild)", () => {
-      // These pin the drift the May 2026 spec missed: borderColor moved from
-      // color7 to color5, textMuted from color10 to color11.
-      expect(result.semantic.borderColor?.alias).toBe("color5");
-      expect(result.semantic.borderColorHover?.alias).toBe("color6");
+      // MPO-19 X4: the seven pinned ramp steps were deleted from
+      // `defaultBuilderOptions.getTheme`, so these aliases are the theme
+      // BUILDER's derivation again rather than mpo's re-anchoring. That is
+      // the correction landing, and what this pins is that it landed —
+      // borderColor back off color5, the background states no longer forced.
+      expect(result.semantic.borderColor?.alias).toBe("color4");
       expect(result.semantic.textMuted?.alias).toBe("color11");
-      expect(result.semantic.backgroundPress?.alias).toBe("color5");
-      expect(result.semantic.backgroundActive?.alias).toBe("color4");
       expect(result.semantic.placeholderColor?.alias).toBe("color10");
       expect(result.semantic.surfaceMuted?.alias).toBe("color10");
       expect(result.semantic.borderStrong?.alias).toBe("color7");
@@ -135,13 +135,16 @@ describe("buildFigmaTokens", () => {
   });
 
   describe("sizing", () => {
-    it("mirrors @tamagui/themes tokens with figma-safe names", () => {
-      const sizeTrue = (tokens.size as Record<string, { val: number }>).true.val;
-      expect(result.sizing["size-true"]).toBe(sizeTrue);
-      const radius4 = (tokens.radius as Record<string, { val: number }>)["4"].val;
-      expect(result.sizing["radius-4"]).toBe(radius4);
+    it("mirrors the v5 defaultConfig tokens with figma-safe names", () => {
+      // Read against the ERA the package pins (MPO-19 X13), not against a
+      // transcribed table: v5 keys carry the `$`, values are raw numbers.
+      const size = defaultConfig.tokens.size as Record<string, number>;
+      expect(result.sizing["size-true"]).toBe(size.$true);
+      expect(result.sizing["radius-4"]).toBe(
+        (defaultConfig.tokens.radius as Record<string, number>)["4"],
+      );
       expect(result.sizing["space-1-5"]).toBe(
-        (tokens.space as Record<string, { val: number }>)["1.5"].val,
+        (defaultConfig.tokens.space as Record<string, number>)["$1.5"],
       );
     });
 
@@ -181,7 +184,7 @@ describe("buildFigmaTokens", () => {
       const { modes } = result.knobs.elevation;
       expect(modes.none).toEqual({ sizeToken: null, px: null });
       expect(modes.small.sizeToken).toBe("$1");
-      expect(modes.small.px).toBe((tokens.size as Record<string, { val: number }>)["1"].val);
+      expect(modes.small.px).toBe((defaultConfig.tokens.size as Record<string, number>).$1);
       expect(modes.medium.sizeToken).toBe("$2");
       expect(modes.large.sizeToken).toBe("$4");
     });
@@ -216,17 +219,18 @@ describe("buildFigmaTokens", () => {
 
   describe("typography (closes deferred task 10.0)", () => {
     it("exports heading/body size + lineHeight tables from the built default fonts", () => {
-      // Heading scale is 1.4x Inter base: H1 $10 = round(46 * 1.4) = 64.
-      expect(result.typography.heading.size["10"]).toBe(64);
-      expect(result.typography.body.size.true).toBe(14);
-      // lineHeight = size + 10 (defaults/fonts.ts).
-      expect(result.typography.body.lineHeight.true).toBe(24);
-      expect(result.typography.heading.lineHeight["10"]).toBe(74);
+      // MPO-19 X8/X9: heading rides the body scale now, so H1 $10 is 40 at
+      // weight 800 rather than 64 at 400, and body $true is v5's 15 with the
+      // tapering leading instead of v4's 14 with `size + 10`.
+      expect(result.typography.heading.size["10"]).toBe(40);
+      expect(result.typography.body.size.true).toBe(15);
+      expect(result.typography.body.lineHeight.true).toBe(23);
+      expect(result.typography.heading.lineHeight["10"]).toBe(50);
     });
 
     it("exports Inter dynamic tracking per size", () => {
       const body = result.typography.body;
-      expect(body.letterSpacing.true).toBe(interTrackingPx(14));
+      expect(body.letterSpacing.true).toBe(interTrackingPx(15));
       expect(Object.keys(body.letterSpacing).length).toBeGreaterThanOrEqual(16);
     });
 

package/src/figma/figmaTokens.ts

@@ -93,7 +93,7 @@ export interface FigmaRadiusMode {
   /** `Sizing` collection variable to alias (e.g. `radius-4`). */
   figmaName: string;
   px: number;
-  /** Outer/nested radius fragment (`knobProps.borderRadiusOuter`). */
+  /** Outer/nested radius fragment (`knobProps.borderRadiusNested`). */
   outerToken: string;
   outerFigmaName: string;
   outerPx: number;
@@ -344,7 +344,7 @@ function buildKnobs(): FigmaKnobsExport {
   for (const mode of RADIUS_KNOB_MODES) {
     const { knobProps } = resolveKnobs({ ...defaultKnobs, borderRadius: mode });
     const token = String(knobProps.borderRadius.borderRadius);
-    const outerToken = String(knobProps.borderRadiusOuter.borderRadius);
+    const outerToken = String(knobProps.borderRadiusNested.borderRadius);
     borderRadius[mode] = {
       token,
       figmaName: tokenToFigma(token, "radius"),

package/src/font.ts

@@ -1,25 +1,12 @@
 import type { GenericFont } from "@tamagui/web";
 import { createFont } from "@tamagui/web";
+import { bodyFontSizes, bodyLineHeightPx } from "./theme/defaults/fonts";
 
 const defaults = {
-  size: {
-    1: 11,
-    2: 12,
-    3: 13,
-    4: 14,
-    5: 15,
-    6: 16,
-    7: 18,
-    8: 21,
-    9: 28,
-    10: 42,
-    11: 52,
-    12: 62,
-    13: 72,
-    14: 92,
-    15: 114,
-    16: 124,
-  } as const,
+  // Same size table as Inter body, including `true: 14`. A missing `true`
+  // key is what collapsed `$serif`/`$mono`/`$rounded` to -apple-system
+  // 14px/normal on the label text node (MPO-44).
+  size: bodyFontSizes,
   // Neutral by default (LC-11): tracking is a per-family function of size,
   // so a shared constant table is always wrong for someone — the previous
   // Inter-ish table leaked +3px tracking into mono/script faces at $5/$6
@@ -37,7 +24,7 @@ export function createDefaultFont<A extends GenericFont>(
   const size = font.size || defaults.size;
   return createFont({
     lineHeight: Object.fromEntries(
-      Object.entries(size).map(([k, v]) => [k, typeof v === "number" ? v * 1.2 + 6 : v]),
+      Object.entries(size).map(([k, v]) => [k, typeof v === "number" ? bodyLineHeightPx(v) : v]),
     ) as typeof size,
     letterSpacing: defaults.letterSpacing,
     weight: defaults.weight,

package/src/keyboardFocusRing.ts

@@ -36,15 +36,21 @@ export function wasKeyboardFocus(): boolean {
   return lastInputWasKeyboard;
 }
 
-import { FOCUS_VISIBLE_RING } from "./theme/focusState";
+import { FOCUS_VISIBLE_RING_INSET } from "./theme/focusState";
 
 /**
- * Standard manual ring props — the SAME geometry as `FOCUS_VISIBLE_RING`
- * (2px solid `$outlineColor`, inset −2), spread here so manually-painted
- * rings and `focusVisibleStyle` rings can never drift apart.
+ * Standard manual ring props — the INSET ring geometry
+ * (`FOCUS_VISIBLE_RING_INSET`: 2px solid `$outlineColor`, offset −2), spread
+ * here so manually-painted rings can never drift from the theme contract.
+ * Manual painting exists for roving-focus / activedescendant composites
+ * (ToggleGroup segments inside a clipped Group, menu/listbox rows under a
+ * clipped overlay, table rows and cells) — items inside clipping ancestors,
+ * which is exactly the LC-71 §4 inset carve-out; an offset-0 band there
+ * would be severed by the clip. Standalone controls take the offset-0
+ * `FOCUS_VISIBLE_RING` via `focusVisibleStyle` / `ensureFocusVisibleRing()`.
  */
 export const keyboardFocusRingProps = {
-  ...FOCUS_VISIBLE_RING,
+  ...FOCUS_VISIBLE_RING_INSET,
 } as const;
 
 /**
@@ -85,7 +91,7 @@ export const compositeFocusRingCss = `/* LC-71: ring on the composite outer box;
 }
 .mp-chip-dismiss:focus-visible .mp-chip-dismiss-ring {
   outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText));
-  outline-offset: 2px;
+  outline-offset: 0;
 }`;
 
 const COMPOSITE_RING_STYLE_ID = "mp-composite-focus-ring";

package/src/theme/FontKnobStyles.tsx

@@ -27,6 +27,7 @@
  */
 import { getConfig } from "@tamagui/web";
 import { useEffect } from "react";
+import { fontCategoryStacks } from "./fontCategoryStacks";
 import type { FontCategory } from "./knobs";
 import { defaultKnobs } from "./knobs";
 import { usePresetContext } from "./PresetContext";
@@ -90,7 +91,8 @@ export interface FontScopeTables {
 /**
  * Resolve the concrete font-family stack registered in the Tamagui config for
  * a font category. Returns undefined when the category font is not registered
- * (the caller then leaves the default family in place).
+ * (the caller then uses `fontCategoryStacks` so the knob still writes
+ * `--f-family` — live SHC console had the style tag and skipped the family).
  */
 export function getConfiguredFontFamily(category: FontCategory): string | undefined {
   let config: ReturnType<typeof getConfig> | undefined;
@@ -202,13 +204,13 @@ export function buildFontKnobCss(
     defaultLeadingRule("body", bodyFont),
   ];
   if (headingFont !== "sans-serif") {
-    const family = resolveFamily(headingFont);
+    const family = resolveFamily(headingFont) ?? fontCategoryStacks[headingFont];
     if (family) {
       rules.push(buildScopeRule("heading", headingFont, family, resolveTables("heading")));
     }
   }
   if (bodyFont !== "sans-serif") {
-    const family = resolveFamily(bodyFont);
+    const family = resolveFamily(bodyFont) ?? fontCategoryStacks[bodyFont];
     if (family) {
       rules.push(buildScopeRule("body", bodyFont, family, resolveTables("body")));
     }

package/src/theme/Tint.tsx

@@ -13,7 +13,8 @@ export interface TintProps extends PropsWithChildren {
 
 /**
  * Depth-based tint component. Each nesting level increments the depth
- * and selects a tint from the preset's tints array via modulo.
+ * and selects a tint from the preset's tints array via
+ * `tints[(depth - 1) % length]` so the first Tint is `tints[0]`.
  *
  * Applies a tint sub-theme based on nesting depth.
  */
@@ -21,7 +22,7 @@ export function Tint({ children, alt = 0, disable, ...props }: TintProps) {
   const parentDepth = useContext(TintDepthContext);
   const depth = parentDepth + 1 + alt;
   const tints = usePresetTints();
-  const tint = tints.length > 0 ? tints[depth % tints.length] : undefined;
+  const tint = tints.length > 0 ? tints[(depth - 1) % tints.length] : undefined;
 
   return (
     <TintDepthContext.Provider value={depth}>

package/src/theme/animations/css.ts

@@ -1,10 +1,23 @@
 import { createAnimations } from "@tamagui/animations-css";
 
+/**
+ * The CSS driver's named durations.
+ *
+ * `bouncy`, `lazy`, `slow`, `medium` and `quick` are Tamagui's own names and
+ * carry Tamagui's own values — a shared name that means something different
+ * here is worse than no name, because every consumer reading `animation="medium"`
+ * against the upstream docs gets a different answer than the one it renders.
+ * MPO-19 X10: `medium` was `ease-in-out 250ms` against stock `ease-in 300ms`,
+ * with no improvement argument written down anywhere.
+ *
+ * `tooltip`, `snappy` and `gentle` are additive — names Tamagui does not use,
+ * so they are ours to set and are not a contradiction.
+ */
 export const animationConfig = {
   bouncy: "ease-in 200ms",
   lazy: "ease-in 600ms",
   slow: "ease-in 500ms",
-  medium: "ease-in-out 250ms",
+  medium: "ease-in 300ms",
   quick: "ease-in 100ms",
   tooltip: "ease-in 400ms",
   snappy: "ease-out 80ms",

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,225 @@ 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/);
+  });
+});