@multiplatform.one/theme 7.4.1 → 7.6.0

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,24 @@
+import { defaultFonts } from "./fonts";
+
+/**
+ * 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).
+ *
+ * Picked out of `defaultFonts` rather than built a second time: two
+ * construction paths meant `$mono` could be registered from one stack here
+ * and another there, which is the same one-source failure MPO-44 was about.
+ */
+export const defaultCategoryFonts = {
+  serif: defaultFonts.serif,
+  mono: defaultFonts.mono,
+  slab: defaultFonts.slab,
+  rounded: defaultFonts.rounded,
+  condensed: defaultFonts.condensed,
+  cursive: defaultFonts.cursive,
+  handwriting: defaultFonts.handwriting,
+  pixel: defaultFonts.pixel,
+  blackletter: defaultFonts.blackletter,
+  geometric: defaultFonts.geometric,
+};

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

@@ -1,5 +1,15 @@
 import { describe, expect, it } from "vitest";
-import { defaultBodyFont, defaultHeadingFont, interTrackingPx } from "./fonts";
+import { createDefaultFont } from "../../font";
+import { flooredLineHeight, fontCategoryMetrics } from "../fontCategoryMetrics";
+import { fontCategoryStacks } from "../fontCategoryStacks";
+import type { FontCategory } from "../knobs";
+import {
+  defaultBodyFont,
+  defaultFonts,
+  defaultHeadingFont,
+  fontFamilyStacks,
+  interTrackingPx,
+} from "./fonts";
 
 type NumTable = Record<string, number>;
 
@@ -14,6 +24,17 @@ function table(font: unknown, key: "size" | "lineHeight" | "letterSpacing"): Num
   return out;
 }
 
+/** Unwrap a font table whose values are strings (weight). */
+function strTable(font: unknown, key: "weight"): Record<string, string> {
+  const raw = (font as Record<string, Record<string, string | { val: string }>>)[key] ?? {};
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const str = typeof v === "string" ? v : v && typeof v.val === "string" ? v.val : undefined;
+    if (str !== undefined) out[k.replace(/^\$/, "")] = str;
+  }
+  return out;
+}
+
 describe("default heading/body fonts — tracking-by-size (Axiom 15 OPTICS, LC-11)", () => {
   for (const [name, font] of [
     ["heading", defaultHeadingFont],
@@ -57,7 +78,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 +89,152 @@ 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 — one ladder, distinct families (MPO-44)", () => {
+  const bodyStops = ["body", "serif", "mono", "rounded"] as const;
+  const firstFamily = (stack: string) => stack.split(",")[0]?.replace(/['"]/g, "").trim();
+  const categories = Object.keys(defaultFonts).filter(
+    (name) => name !== "heading" && name !== "body",
+  ) as FontCategory[];
+  const bodySize = table(defaultBodyFont, "size");
+  const bodyLineHeight = table(defaultBodyFont, "lineHeight");
+
+  it("registers every category token the bodyFont knob maps to", () => {
+    expect(categories.length).toBe(10);
+    for (const key of categories) {
+      expect(defaultFonts[key], key).toBeTruthy();
+      expect(fontFamily(defaultFonts[key])).toBe(fontCategoryStacks[key]);
+    }
+    expect(fontFamily(defaultFonts.body)).toContain("Inter");
+  });
+
+  it("aliases fontFamilyStacks to the one fontCategoryStacks table", () => {
+    expect(fontFamilyStacks).toBe(fontCategoryStacks);
+  });
+
+  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("every knob stop has a distinct first family — none is a system fallback", () => {
+    const firsts = ["body", ...categories].map((key) =>
+      firstFamily(fontFamily(defaultFonts[key as keyof typeof defaultFonts])),
+    );
+    expect(new Set(firsts).size).toBe(firsts.length);
+    expect(firsts).not.toContain("-apple-system");
+  });
+
+  it("puts every category font on the $body SIZE ladder — a family knob never resizes", () => {
+    for (const name of categories) {
+      expect(table(defaultFonts[name], "size"), `${name}.size`).toEqual(bodySize);
+    }
+  });
+
+  it("renders 15px/23px at $true and $4 on every stop, body included", () => {
+    for (const name of ["body", ...categories] as const) {
+      const size = table(defaultFonts[name as keyof typeof defaultFonts], "size");
+      const lineHeight = table(defaultFonts[name as keyof typeof defaultFonts], "lineHeight");
+      expect(size.true, `${name}.size.true`).toBe(15);
+      expect(size["4"], `${name}.size.4`).toBe(15);
+      expect(lineHeight.true, `${name}.lineHeight.true`).toBe(23);
+      expect(lineHeight["4"], `${name}.lineHeight.4`).toBe(23);
+    }
+  });
+
+  it("takes the era's leading, raised to the category floor and never lowered (LC-11)", () => {
+    for (const name of categories) {
+      const lineHeight = table(defaultFonts[name], "lineHeight");
+      const minRatio = fontCategoryMetrics[name].body;
+      for (const [key, px] of Object.entries(bodySize)) {
+        expect(lineHeight[key], `${name}.lineHeight[${key}]`).toBe(
+          flooredLineHeight(px, bodyLineHeight[key] as number, minRatio),
+        );
+        expect(lineHeight[key]).toBeGreaterThanOrEqual(bodyLineHeight[key] as number);
+        expect((lineHeight[key] as number) / px, `${name} ratio at ${key}`).toBeGreaterThanOrEqual(
+          minRatio - 0.034,
+        );
+      }
+    }
+  });
+
+  it("meets the LC-11 body floor at every size on every category", () => {
+    for (const name of categories) {
+      const size = table(defaultFonts[name], "size");
+      const lineHeight = table(defaultFonts[name], "lineHeight");
+      for (const [key, px] of Object.entries(size)) {
+        expect((lineHeight[key] as number) / px, `${name} ratio at ${key}`).toBeGreaterThan(1.36);
+      }
+    }
+  });
+
+  it("carries the era's weight, not the legacy 300", () => {
+    for (const name of categories) {
+      const weight = strTable(defaultFonts[name], "weight");
+      for (const key of Object.keys(bodySize)) {
+        expect(weight[key], `${name}.weight[${key}]`).toBe("400");
+      }
+    }
+  });
+
+  it("zeroes tracking on every category face so Inter's curve cannot leak in", () => {
+    for (const name of categories) {
+      const letterSpacing = table(defaultFonts[name], "letterSpacing");
+      expect(Object.keys(letterSpacing).sort(), `${name}.letterSpacing keys`).toEqual(
+        Object.keys(bodySize).sort(),
+      );
+      for (const key of Object.keys(bodySize)) {
+        expect(letterSpacing[key], `${name}.letterSpacing[${key}]`).toBe(0);
+      }
+    }
+  });
+});
+
+describe("createDefaultFont — the era body ramp (MPO-44)", () => {
+  it("includes $true at 15/23 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(15);
+    expect(lineHeight.true).toBe(23);
+    expect(fontFamily(font)).toBe("Georgia, serif");
+  });
+
+  it("lands a consumer font on the same ladder as the built-in category fonts", () => {
+    const font = createDefaultFont({ family: "Georgia, serif" });
+    expect(table(font, "size")).toEqual(table(defaultFonts.serif, "size"));
+    expect(table(font, "lineHeight")).toEqual(table(defaultFonts.rounded, "lineHeight"));
+  });
+
+  it("defaults to weight 400, never the legacy 300", () => {
+    const weight = strTable(createDefaultFont({ family: "Georgia, serif" }), "weight");
+    expect(weight["4"]).toBe("400");
+  });
+});
+
+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,139 @@
+/**
+ * @vitest-environment happy-dom
+ *
+ * Theme spec (MPO-44): bodyFont family, size and leading measured on the
+ * RENDERED TEXT NODE.
+ *
+ * Two traps this file exists to stay clear of.
+ *
+ * The button FRAME is always Inter — measuring it hid mono/serif/rounded
+ * collapsing to -apple-system 14px/normal. So walk to the text node.
+ *
+ * And the measurement must come out of `getComputedStyle`, never out of the
+ * class name. An earlier version of this spec read `font_serif` off the
+ * element and then looked the family up in the source table, which asserts
+ * that the table is the table. It also wrote `expect(parseFloat(lh) || 24)`,
+ * which passes when the leading is unreadable, and guarded the size check
+ * behind `if (fontSize)`. Every assertion below reads a real computed value
+ * and fails when there is none.
+ */
+
+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";
+
+const themeConfig = createDefaultThemeConfig();
+
+/** The stops the button-knobs board shoots, in board order. */
+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;
+
+/** One ladder for every stop: `$true` is the era's body step (MPO-19 X8/X9). */
+const LABEL_SIZE_PX = 15;
+const LABEL_LEADING_PX = 23;
+
+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" }, label),
+    ),
+  );
+  const host = textNodeHost(container, label);
+  const cs = getComputedStyle(host);
+  const px = (value: string) => {
+    const n = Number.parseFloat(value);
+    if (!Number.isFinite(n)) throw new Error(`unreadable length ${JSON.stringify(value)}`);
+    return n;
+  };
+  const family = cs.fontFamily.trim();
+  if (!family) throw new Error("no computed font-family on the text node");
+  return {
+    host,
+    knobs,
+    family,
+    firstFamily: family.split(",")[0]?.replace(/['"]/g, "").trim() ?? "",
+    fontSize: px(cs.fontSize),
+    lineHeight: cs.lineHeight.trim(),
+    lineHeightPx: px(cs.lineHeight),
+    letterSpacing: cs.letterSpacing.trim(),
+  };
+}
+
+describe("bodyFont text-node family, size 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} ${LABEL_SIZE_PX}px/${LABEL_LEADING_PX}px`, () => {
+          const m = measureLabel(stop, scheme);
+          expect(m.knobs.knobProps.body.fontFamily).toBe(`$${token}`);
+
+          // Trap: a wrapping frame stays Inter. We measured the text node.
+          expect([...m.host.childNodes].some((n) => n.nodeType === Node.TEXT_NODE)).toBe(true);
+
+          expect(m.firstFamily.toLowerCase()).toBe(firstFamily.toLowerCase());
+          // The Inter stack legitimately names -apple-system as a fallback;
+          // the defect was it arriving FIRST, which is what the text node reads.
+          expect(m.firstFamily.toLowerCase()).not.toBe("-apple-system");
+
+          expect(m.lineHeight.toLowerCase()).not.toBe("normal");
+          expect(m.lineHeightPx).toBe(LABEL_LEADING_PX);
+          expect(m.fontSize).toBe(LABEL_SIZE_PX);
+          expect(m.lineHeightPx / m.fontSize).toBeGreaterThanOrEqual(1.4);
+        });
+      }
+
+      it("the four stops resolve to four distinct family stacks", () => {
+        const families = BODY_STOPS.map((s) => measureLabel(s.stop, scheme).firstFamily);
+        expect(new Set(families).size).toBe(4);
+        expect(families.some((f) => f.toLowerCase() === "-apple-system")).toBe(false);
+      });
+
+      it("flipping the family knob moves the family and nothing else", () => {
+        const measured = BODY_STOPS.map((s) => measureLabel(s.stop, scheme));
+        const sizes = new Set(measured.map((m) => m.fontSize));
+        const leadings = new Set(measured.map((m) => m.lineHeightPx));
+        expect([...sizes]).toEqual([LABEL_SIZE_PX]);
+        expect([...leadings]).toEqual([LABEL_LEADING_PX]);
+      });
+
+      it("does not leak Inter's optical tracking onto the other faces (LC-11)", () => {
+        for (const { stop } of BODY_STOPS.filter((s) => s.stop !== "sans-serif")) {
+          const m = measureLabel(stop, scheme);
+          expect(Number.parseFloat(m.letterSpacing) || 0, `${stop} tracking`).toBe(0);
+        }
+        // Inter keeps its curve.
+        expect(Number.parseFloat(measureLabel("sans-serif", scheme).letterSpacing)).toBeLessThan(0);
+      });
+    });
+  }
+});