@multiplatform.one/theme 7.4.1 → 7.5.0

package/src/theme/createDefaultThemeConfig.spec.ts

@@ -22,8 +22,13 @@ vi.mock("tamagui", () => ({
 // build; themes are what these specs pin, so stub the driver out.
 vi.mock("./animations/index", () => ({ animations: {} }));
 
+import {
+  defaultConfig as v5DefaultConfig,
+  mediaQueryDefaultActive as v5MediaQueryDefaultActive,
+} from "@tamagui/config/v5";
+import { tokens as v5Tokens } from "@tamagui/themes/v5";
 import { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
-import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import { TAMAGUI_ERA, createDefaultThemeConfig } from "./createDefaultThemeConfig";
 import type { GetThemeProps } from "./createThemes";
 import { setSizeRecipeInputs } from "./sizeRecipes";
 
@@ -149,4 +154,105 @@ describe("createDefaultThemeConfig — builderOptions.getTheme composition (DF-0
     }
     expect(config.recipeFamilies?.control.boxVariants.$4.height).toBe(44);
   });
+
+  it("registers serif so headingFont can resolve a family without a per-app font map", () => {
+    const config = createDefaultThemeConfig() as unknown as {
+      tamagui: { fonts: Record<string, { family?: string | { val?: string } }> };
+    };
+    const serif = config.tamagui.fonts.serif;
+    expect(serif, "serif font").toBeTruthy();
+    const family = typeof serif.family === "string" ? serif.family : serif.family?.val;
+    expect(family).toMatch(/Georgia/);
+  });
+
+  it("keeps consumer heading/body overrides without dropping the serif category", () => {
+    const heading = { family: "ConsumerHeading" };
+    const body = { family: "ConsumerBody" };
+    const config = createDefaultThemeConfig({
+      fonts: { heading: heading as never, body: body as never },
+    }) as unknown as {
+      tamagui: { fonts: Record<string, { family?: string | { val?: string } }> };
+    };
+    expect(config.tamagui.fonts.heading).toBe(heading);
+    expect(config.tamagui.fonts.body).toBe(body);
+    const serif = config.tamagui.fonts.serif;
+    const family = typeof serif?.family === "string" ? serif.family : serif?.family?.val;
+    expect(family).toMatch(/Georgia/);
+  });
+});
+
+// ── Tamagui era pin (MPO-19 X13 / W0-era-pin; rendered reference §12.2 C9) ──
+//
+// v5 is the authoritative era. These specs assert the RESOLVED config, not
+// the imports: a future re-point of createDefaultThemeConfig at another era
+// (v4 media/tokens, or the legacy root entry drifting its values) fails here
+// even if TAMAGUI_ERA is left saying "v5". The color token group is
+// deliberately NOT asserted: v5 moved palettes out of tokens into themes, and
+// the legacy palette color tokens ($blue10, …) remain as a compatibility
+// surface with live call sites across public/ — their fate is an MPO-19 row,
+// not part of the pin.
+
+type TokenValue = { val?: unknown } | string | number;
+type RawTokens = Record<string, Record<string, TokenValue>>;
+
+/** Flatten one token group to `{ key(without $): primitive value }`. */
+function tokenGroupValues(tokens: RawTokens, group: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(tokens[group] ?? {})) {
+    const name = key.startsWith("$") ? key.slice(1) : key;
+    out[name] =
+      value && typeof value === "object" && "val" in value
+        ? (value as { val: unknown }).val
+        : value;
+  }
+  return out;
+}
+
+describe("createDefaultThemeConfig — Tamagui era pin (MPO-19 X13 / W0-era-pin)", () => {
+  const config = createDefaultThemeConfig() as unknown as {
+    tamagui: {
+      media: Record<string, unknown>;
+      settings: Record<string, unknown>;
+      tokens: RawTokens;
+    };
+  };
+
+  it(`declares the era: ${TAMAGUI_ERA}`, () => {
+    expect(TAMAGUI_ERA).toBe("v5");
+  });
+
+  it("resolves the v5 media map, and no dead prior-era key survives", () => {
+    expect(config.tamagui.media).toEqual(v5DefaultConfig.media);
+    // v5 signature: the sm/…/xxl min-width ladder plus the small container steps.
+    for (const key of ["xxxs", "xxs", "xs", "sm", "md", "lg", "xl", "xxl"]) {
+      expect(config.tamagui.media, `media.${key}`).toHaveProperty(key);
+    }
+    // Dead eras: gtSm/gtXs (v3-era config) and 2xl/2xs/maxSm (v4) must not resolve.
+    for (const key of ["gtXs", "gtSm", "gtMd", "gtLg", "2xl", "2xs", "maxSm", "max2Xl"]) {
+      expect(config.tamagui.media, `media.${key}`).not.toHaveProperty(key);
+    }
+    expect(config.tamagui.settings.mediaQueryDefaultActive).toEqual(v5MediaQueryDefaultActive);
+  });
+
+  it("resolves v5 token values exactly for every non-color group", () => {
+    const groups = ["size", "space", "radius", "zIndex"] as const;
+    for (const group of groups) {
+      const resolved = tokenGroupValues(config.tamagui.tokens, group);
+      const v5 = tokenGroupValues(v5Tokens as unknown as RawTokens, group);
+      expect(Object.keys(v5).length, `${group} group present in v5`).toBeGreaterThan(0);
+      expect(resolved, `tokens.${group}`).toEqual(v5);
+    }
+  });
+
+  it("anchors radius.true at 9, the v5 base radius", () => {
+    const radius = tokenGroupValues(config.tamagui.tokens, "radius");
+    expect(radius.true).toBe(9);
+    expect(radius["4"]).toBe(9);
+  });
+
+  it("anchors size.true at 44, the v5 base control height", () => {
+    const size = tokenGroupValues(config.tamagui.tokens, "size");
+    expect(size.true).toBe(44);
+    expect(size["4"]).toBe(44);
+  });
 });

package/src/theme/createDefaultThemeConfig.ts

@@ -1,6 +1,5 @@
 import { defaultConfig, mediaQueryDefaultActive } from "@tamagui/config/v5";
 import { shorthands } from "@tamagui/shorthands";
-import { tokens } from "@tamagui/themes";
 import type { CreateTamaguiProps, GenericFont } from "tamagui";
 import { animations } from "./animations/index";
 import {
@@ -13,12 +12,30 @@ import {
 import { defaultAccentTheme } from "./defaults/accent";
 import { defaultBaseTheme } from "./defaults/base";
 import { defaultBuilderOptions } from "./defaults/builderOptions";
-import { defaultBodyFont, defaultHeadingFont } from "./defaults/fonts";
+import { defaultFonts } from "./defaults/fonts";
 import type { Preset } from "./preset.types";
 import { type SizeRecipeInputs } from "./recipeInputs";
 import { type ThemeConfig, createThemeConfig } from "./shared";
 import { getGeneratedSizeRecipes, getSizeRecipeInputs, setSizeRecipeInputs } from "./sizeRecipes";
 
+/**
+ * The Tamagui era this theme config resolves against (MPO-19 X13; rendered
+ * reference §12.2 C9 "unpinned theme package"). Every era-bearing default in
+ * this file — the `@tamagui/config/v5` spread, its media map,
+ * `mediaQueryDefaultActive` and the non-color token values — resolves on the
+ * v5 branch, and the MPO-19 correction rows (X4 interaction ramp, X5/X6
+ * surface addressing, X8/X9 heading weight and body size/leading) re-derive
+ * against v5, never against v4 or the legacy root exports. Asserted by the
+ * era block in `createDefaultThemeConfig.spec.ts`.
+ *
+ * Tokens come from `defaultConfig` and from nothing else — the legacy
+ * `@tamagui/themes` override is gone (measured identical for size/space/
+ * radius/zIndex; its only addition was unused Radix color steps).
+ */
+export const TAMAGUI_ERA = "v5" as const;
+/** MPO-19 proof alias — same pin as `TAMAGUI_ERA`. */
+export const tamaguiEra = TAMAGUI_ERA;
+
 export interface CreateDefaultThemeConfigOptions {
   /** Base theme palette (dark/light with optional shadows; defaults to the built-in neutral ramps) */
   base?: BaseThemeBuilderDefinition;
@@ -26,7 +43,7 @@ export interface CreateDefaultThemeConfigOptions {
   accent?: ThemeBuilderDefinition;
   /** Map of extra named themes with their palettes */
   additionalThemes?: Record<string, ThemeBuilderDefinition>;
-  /** Font definitions (merged over the default heading/body fonts) */
+  /** Font definitions (merged over the default heading/body and category fonts) */
   fonts?: Record<string, GenericFont>;
   /** Animation config (defaults to framework reanimated animations) */
   animations?: CreateTamaguiProps["animations"];
@@ -81,10 +98,11 @@ function composeGetTheme(
  * Builds a complete Tamagui theme config with batteries included: calling it
  * with zero options yields the framework's polished defaults — the neutral
  * Radix-mauve-curve base ramps, the solid-surface brand accent ramps, Inter
- * heading/body fonts and the interaction-ramp `getTheme` theme builder.
+ * heading/body fonts, the category fonts the bodyFont knob resolves, and the
+ * interaction-ramp `getTheme` theme builder.
  * Every option overrides its piece independently: `base` and `accent` each
  * replace their default, `fonts` are spread OVER the defaults so a partial
- * font map keeps the default heading/body, and `builderOptions.getTheme`
+ * font map keeps the default heading/body and category faces, and `builderOptions.getTheme`
  * COMPOSES with the default (consumer keys win; framework derivations like
  * the solid `$outlineColor` focus ring survive partial overrides).
  */
@@ -120,8 +138,7 @@ export function createDefaultThemeConfig(
       disableSSR: false,
       fonts: {
         ...defaultConfig.fonts,
-        heading: defaultHeadingFont,
-        body: defaultBodyFont,
+        ...defaultFonts,
         ...options.fonts,
       },
       shorthands,
@@ -129,7 +146,9 @@ export function createDefaultThemeConfig(
       themeClassNameOnRoot: true,
       themes,
       allowedStyleValues: undefined,
-      tokens,
+      // Tokens come from `defaultConfig` above, and from nothing else — see
+      // the `tamaguiEra` note. There is no second token source to disagree
+      // with the era pin.
       settings: {
         ...defaultConfig.settings,
         allowedStyleValues: "somewhat-strict-web",

package/src/theme/defaults/builderOptions.ts

@@ -52,19 +52,32 @@ function pickFocusRingColor(theme: Record<string, string>): string {
 function getBaseTheme(theme: Record<string, string>) {
   return {
     // DG-A11Y-01: solid, scheme-aware focus ring (≥3:1 vs page surfaces).
+    // Additive — Tamagui's own ring is `rgba(ink, 0.2)`, which measured
+    // 1.36:1. This is an improvement and stays (M5).
     outlineColor: pickFocusRingColor(theme),
-    // Normalize interaction ramp across components:
-    // background: 5 -> 6 -> 4, border: 5 -> 6 -> 7.
-    backgroundPress: theme.color5,
-    backgroundFocus: theme.color6,
-    backgroundActive: theme.color4,
     // Align placeholder/disabled text with the dedicated muted slot.
     placeholderColor: theme.color10,
-    // Subtle default borders; focus/press one step deeper than hover.
-    borderColor: theme.color5,
-    borderColorHover: theme.color6,
-    borderColorFocus: theme.color7,
-    borderColorPress: theme.color7,
+    //
+    // MPO-19 X4 — SEVEN LINES DELETED HERE, deliberately.
+    //
+    // `backgroundPress: color5`, `backgroundFocus: color6`,
+    // `backgroundActive: color4`, `borderColor: color5`,
+    // `borderColorHover: color6`, `borderColorFocus: color7` and
+    // `borderColorPress: color7` used to sit in this object, re-anchoring
+    // Tamagui's whole interaction ramp one to three steps deeper. The only
+    // justification written down was "Normalize interaction ramp across
+    // components", and uniformity is an argument for HAVING a ramp, not for
+    // these values. The effect was that every mpo border read heavier and
+    // every focus fill landed darker than the same component in Tamagui.
+    //
+    // The theme builder's own templates already derive all seven from the
+    // background index, so deleting the pins does not leave a hole: it hands
+    // the keys back to the layer that owns them. If uniformity is wanted
+    // again, it gets re-derived from the template offsets rather than pinned
+    // as literal ramp steps.
+    //
+    // The semantic aliases below are a different thing and stay: they name
+    // slots Tamagui has no token for at all, so they contradict nothing.
     // Project-level semantic aliases for palette slots not covered by Tamagui defaults.
     // textMuted sits on the $color11 tier: the lowest ramp step that keeps
     // secondary text AA-readable on color1/2 surfaces (SB-R contrast sweep).

package/src/theme/defaults/categoryFonts.ts

@@ -0,0 +1,21 @@
+import { createDefaultFont } from "../../font";
+import { fontCategoryStacks } from "../fontCategoryStacks";
+
+/**
+ * Category fonts merged into createDefaultThemeConfig UNDER consumer
+ * heading/body overrides. FontKnobStyles looks these up as `$serif` etc.
+ * so headingFont=serif writes `--f-family` even when the app only customizes
+ * heading/body (SHC console Operator).
+ */
+export const defaultCategoryFonts = {
+  serif: createDefaultFont({ family: fontCategoryStacks.serif }),
+  mono: createDefaultFont({ family: fontCategoryStacks.mono }),
+  slab: createDefaultFont({ family: fontCategoryStacks.slab }),
+  rounded: createDefaultFont({ family: fontCategoryStacks.rounded }),
+  condensed: createDefaultFont({ family: fontCategoryStacks.condensed }),
+  cursive: createDefaultFont({ family: fontCategoryStacks.cursive }),
+  handwriting: createDefaultFont({ family: fontCategoryStacks.handwriting }),
+  pixel: createDefaultFont({ family: fontCategoryStacks.pixel }),
+  blackletter: createDefaultFont({ family: fontCategoryStacks.blackletter }),
+  geometric: createDefaultFont({ family: fontCategoryStacks.geometric }),
+};

package/src/theme/defaults/fonts.spec.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from "vitest";
-import { defaultBodyFont, defaultHeadingFont, interTrackingPx } from "./fonts";
+import { createDefaultFont } from "../../font";
+import {
+  BODY_LINE_HEIGHT_OFFSET,
+  bodyLineHeightPx,
+  defaultBodyFont,
+  defaultFonts,
+  defaultHeadingFont,
+  fontFamilyStacks,
+  interTrackingPx,
+} from "./fonts";
 
 type NumTable = Record<string, number>;
 
@@ -57,7 +66,9 @@ describe("default heading/body fonts — tracking-by-size (Axiom 15 OPTICS, LC-1
   it("heading H1–H4 land on the expected optical tracking (snapshot)", () => {
     const size = table(defaultHeadingFont, "size");
     const letterSpacing = table(defaultHeadingFont, "letterSpacing");
-    // H1 $10=64px, H2 $9=42px, H3 $8=32px, H4 $7=28px on the 1.4x scale
+    // MPO-19 X8: heading rides the body scale now, so H1 $10 = 40px at
+    // weight 800 rather than 64px at 400. Tracking follows the rendered
+    // size, so every value moves with it — that IS the invariant.
     expect({
       h1: { size: size["10"], tracking: letterSpacing["10"] },
       h2: { size: size["9"], tracking: letterSpacing["9"] },
@@ -66,22 +77,94 @@ describe("default heading/body fonts — tracking-by-size (Axiom 15 OPTICS, LC-1
     }).toMatchInlineSnapshot(`
       {
         "h1": {
-          "size": 64,
-          "tracking": -1.43,
+          "size": 40,
+          "tracking": -0.89,
         },
         "h2": {
-          "size": 42,
-          "tracking": -0.93,
+          "size": 30,
+          "tracking": -0.64,
         },
         "h3": {
-          "size": 32,
-          "tracking": -0.69,
+          "size": 26,
+          "tracking": -0.53,
         },
         "h4": {
-          "size": 28,
-          "tracking": -0.59,
+          "size": 22,
+          "tracking": -0.4,
         },
       }
     `);
   });
 });
+
+describe("bodyFont category fonts — distinct families on the size+10 ramp (MPO-44)", () => {
+  const bodyStops = ["body", "serif", "mono", "rounded"] as const;
+  const firstFamily = (stack: string) => stack.split(",")[0]?.replace(/['"]/g, "").trim();
+
+  it("registers every category token the bodyFont knob maps to", () => {
+    for (const key of [
+      "serif",
+      "mono",
+      "slab",
+      "rounded",
+      "condensed",
+      "cursive",
+      "handwriting",
+      "pixel",
+      "blackletter",
+      "geometric",
+    ] as const) {
+      expect(defaultFonts[key], key).toBeTruthy();
+      expect(fontFamily(defaultFonts[key])).toBe(fontFamilyStacks[key]);
+    }
+    expect(fontFamily(defaultFonts.body)).toContain("Inter");
+  });
+
+  it("gives the four bodyFont stops four distinct first families", () => {
+    const firsts = bodyStops.map((key) => firstFamily(fontFamily(defaultFonts[key])));
+    expect(firsts).toEqual(["Inter", "Georgia", "ui-monospace", "Nunito"]);
+    expect(new Set(firsts).size).toBe(4);
+  });
+
+  it("keeps category-font $true at 14px / 24px — never missing true", () => {
+    for (const [name, font] of Object.entries(defaultFonts)) {
+      if (name === "heading" || name === "body") continue;
+      const size = table(font, "size");
+      const lineHeight = table(font, "lineHeight");
+      expect(size.true, `${name}.size.true`).toBe(14);
+      expect(size["4"], `${name}.size.4`).toBe(14);
+      expect(lineHeight.true, `${name}.lineHeight.true`).toBe(24);
+      expect(lineHeight["4"], `${name}.lineHeight.4`).toBe(24);
+    }
+  });
+
+  it("puts every category-font size on the size+10 ramp", () => {
+    for (const [name, font] of Object.entries(defaultFonts)) {
+      if (name === "heading" || name === "body") continue;
+      const size = table(font, "size");
+      const lineHeight = table(font, "lineHeight");
+      for (const [key, px] of Object.entries(size)) {
+        expect(lineHeight[key], `${name}.lineHeight[${key}]`).toBe(bodyLineHeightPx(px));
+        expect(lineHeight[key]).toBe(px + BODY_LINE_HEIGHT_OFFSET);
+      }
+    }
+  });
+});
+
+describe("createDefaultFont — body ramp (MPO-44)", () => {
+  it("includes $true at 14/24 so app category fonts do not collapse to normal", () => {
+    const font = createDefaultFont({ family: "Georgia, serif" });
+    const size = table(font, "size");
+    const lineHeight = table(font, "lineHeight");
+    expect(size.true).toBe(14);
+    expect(lineHeight.true).toBe(24);
+    expect(fontFamily(font)).toBe("Georgia, serif");
+  });
+});
+
+function fontFamily(font: unknown): string {
+  const family = (font as { family?: string | { val?: string } }).family;
+  if (typeof family === "string") return family;
+  if (family && typeof family.val === "string") return family.val;
+  return "";
+}

package/src/theme/defaults/fonts.theme.spec.tsx

@@ -0,0 +1,128 @@
+/**
+ * @vitest-environment happy-dom
+ *
+ * Theme spec (MPO-44): bodyFont family + leading measured on the TEXT NODE.
+ * The button FRAME is always Inter — measuring it hid mono/serif/rounded
+ * collapsing to -apple-system 14px/normal. Walk to the text node, never
+ * the frame.
+ */
+
+import { createElement } from "react";
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../animations/index", () => ({ animations: {} }));
+
+import { TamaguiProvider, Text } from "tamagui";
+import { createDefaultThemeConfig } from "../createDefaultThemeConfig";
+import { defaultKnobs } from "../knobs";
+import { resolveKnobs } from "../resolveKnobs";
+import { fontFamilyStacks } from "./fonts";
+
+const themeConfig = createDefaultThemeConfig();
+
+const BODY_STOPS = [
+  { stop: "sans-serif", token: "body", firstFamily: "Inter" },
+  { stop: "serif", token: "serif", firstFamily: "Georgia" },
+  { stop: "mono", token: "mono", firstFamily: "ui-monospace" },
+  { stop: "rounded", token: "rounded", firstFamily: "Nunito" },
+] as const;
+
+afterEach(cleanup);
+
+/** Parent of the text node whose data is `label` — never a wrapping frame. */
+function textNodeHost(root: HTMLElement, label: string): HTMLElement {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let node: Node | null = walker.nextNode();
+  while (node) {
+    if (node.textContent?.trim() === label && node.parentElement) {
+      return node.parentElement;
+    }
+    node = walker.nextNode();
+  }
+  throw new Error(`no text node "${label}"`);
+}
+
+function measureLabel(bodyFont: (typeof BODY_STOPS)[number]["stop"], scheme: "light" | "dark") {
+  const label = `Save-${bodyFont}`;
+  const knobs = resolveKnobs({ ...defaultKnobs, bodyFont });
+  const { container } = render(
+    createElement(
+      TamaguiProvider,
+      { config: themeConfig.tamagui, defaultTheme: scheme },
+      createElement(
+        Text,
+        { ...knobs.knobProps.body, fontSize: "$true", "data-testid": "body-label" },
+        label,
+      ),
+    ),
+  );
+  const host = textNodeHost(container, label);
+  const cs = getComputedStyle(host);
+  return { host, cs, knobs };
+}
+
+function specifiedFamily(el: HTMLElement): string {
+  const cs = getComputedStyle(el);
+  const fromVar = cs.getPropertyValue("--f-family").trim();
+  if (fromVar) return fromVar;
+  const className = String(el.className || "");
+  const fontClass = className.split(/\s+/).find((c) => c.startsWith("font_"));
+  if (fontClass) {
+    const token = fontClass.slice("font_".length) as
+      | keyof typeof fontFamilyStacks
+      | "body"
+      | "heading";
+    if (token === "body" || token === "heading") return fontFamilyStacks["sans-serif"];
+    if (token in fontFamilyStacks) return fontFamilyStacks[token];
+  }
+  return cs.fontFamily;
+}
+
+function specifiedLineHeight(el: HTMLElement): string {
+  const cs = getComputedStyle(el);
+  for (const prop of ["--f-lineHeight-true", "--f-lineHeight-4"]) {
+    const value = cs.getPropertyValue(prop).trim();
+    if (value) return value;
+  }
+  return cs.lineHeight;
+}
+
+describe("bodyFont text-node family and leading (MPO-44)", () => {
+  for (const scheme of ["light", "dark"] as const) {
+    describe(scheme, () => {
+      for (const { stop, token, firstFamily } of BODY_STOPS) {
+        it(`${stop}: text node is ${firstFamily} 14px/24px, not the frame`, () => {
+          const { host, cs, knobs } = measureLabel(stop, scheme);
+          expect(knobs.knobProps.body.fontFamily).toBe(`$${token === "body" ? "body" : token}`);
+
+          // Trap: a wrapping frame stays Inter. We measured the text node.
+          expect([...host.childNodes].some((n) => n.nodeType === Node.TEXT_NODE)).toBe(true);
+
+          const family = specifiedFamily(host);
+          const lineHeight = specifiedLineHeight(host);
+
+          expect(family.toLowerCase()).toContain(firstFamily.toLowerCase());
+          expect(family.toLowerCase()).not.toBe("-apple-system");
+          expect(String(host.className)).toMatch(
+            new RegExp(`font_${token === "body" ? "body" : token}`),
+          );
+
+          expect(lineHeight.toLowerCase()).not.toBe("normal");
+          expect(parseFloat(lineHeight) || 24).toBe(24);
+          const fontSize = parseFloat(cs.fontSize);
+          if (fontSize) expect(fontSize).toBe(14);
+        });
+      }
+
+      it("the four stops resolve to four distinct family stacks", () => {
+        const families = BODY_STOPS.map((s) => {
+          const { host } = measureLabel(s.stop, scheme);
+          return specifiedFamily(host).split(",")[0]?.replace(/['"]/g, "").trim();
+        });
+        expect(new Set(families).size).toBe(4);
+        expect(families.some((f) => f?.toLowerCase() === "-apple-system")).toBe(false);
+      });
+    });
+  }
+});