@multiplatform.one/theme 7.5.0 → 7.6.0

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

@@ -1,10 +1,21 @@
 /**
  * @vitest-environment happy-dom
  *
- * Theme spec (MPO-44): bodyFont family + leading measured on the TEXT NODE.
+ * 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. Walk to the text node, never
- * the frame.
+ * 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";
@@ -17,10 +28,10 @@ import { TamaguiProvider, Text } from "tamagui";
 import { createDefaultThemeConfig } from "../createDefaultThemeConfig";
 import { defaultKnobs } from "../knobs";
 import { resolveKnobs } from "../resolveKnobs";
-import { fontFamilyStacks } from "./fonts";
 
 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" },
@@ -28,6 +39,10 @@ const BODY_STOPS = [
   { 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. */
@@ -50,78 +65,74 @@ function measureLabel(bodyFont: (typeof BODY_STOPS)[number]["stop"], scheme: "li
     createElement(
       TamaguiProvider,
       { config: themeConfig.tamagui, defaultTheme: scheme },
-      createElement(
-        Text,
-        { ...knobs.knobProps.body, fontSize: "$true", "data-testid": "body-label" },
-        label,
-      ),
+      createElement(Text, { ...knobs.knobProps.body, fontSize: "$true" }, 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;
+  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 and leading (MPO-44)", () => {
+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} 14px/24px, not the frame`, () => {
-          const { host, cs, knobs } = measureLabel(stop, scheme);
-          expect(knobs.knobProps.body.fontFamily).toBe(`$${token === "body" ? "body" : token}`);
+        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([...host.childNodes].some((n) => n.nodeType === Node.TEXT_NODE)).toBe(true);
+          expect([...m.host.childNodes].some((n) => n.nodeType === Node.TEXT_NODE)).toBe(true);
 
-          const family = specifiedFamily(host);
-          const lineHeight = specifiedLineHeight(host);
+          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(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);
+          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) => {
-          const { host } = measureLabel(s.stop, scheme);
-          return specifiedFamily(host).split(",")[0]?.replace(/['"]/g, "").trim();
-        });
+        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);
+        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);
       });
     });
   }

package/src/theme/defaults/fonts.ts

@@ -1,6 +1,12 @@
 import { defaultConfig } from "@tamagui/config/v5";
 import { createInterFont } from "@tamagui/font-inter";
-import type { GenericFont } from "tamagui";
+// `@tamagui/web`, not `tamagui`: createDefaultThemeConfig.spec.ts mocks the
+// whole `tamagui` module down to `createTamagui`, and this module is on that
+// spec's import graph.
+import { createFont, type GenericFont } from "@tamagui/web";
+import { flooredLineHeight, fontCategoryMetrics } from "../fontCategoryMetrics";
+import { fontCategoryStacks } from "../fontCategoryStacks";
+import type { FontCategory } from "../knobs";
 
 // Default purpose fonts for components that reference $heading / $body
 // directly, both backed by Inter.
@@ -27,14 +33,44 @@ import type { GenericFont } from "tamagui";
 // increasingly tight at display sizes (the same optical behavior Apple's SF
 // implements per point size). The curve is Inter's own dynamic-metrics
 // model (rsms.me/inter/dynmetrics): tracking(em) = a + b·e^(c·size).
-// These values are Inter-specific: when the headingFont/bodyFont knob picks
-// another family, FontKnobStyles' per-category metrics (LC-11) neutralize
-// this table for fixed-pitch and connected-script categories.
 //
-// Category fonts (serif/mono/rounded/…) MUST be registered on this same
-// size+10 ramp, including the `true` key. An unregistered `$serif` token
-// collapses the label TEXT NODE to -apple-system 14px/normal — the frame
-// stays Inter, so measuring the frame hides the defect (MPO-44).
+// ── Category fonts (MPO-44, re-derived against the era pin) ──────────────
+//
+// A bodyFont stop is a FAMILY choice. It must move the family and nothing
+// else, so every category font is built from the era's own `$body` tables
+// rather than a ramp of its own. Measured on the label text node before this
+// change, both schemes:
+//
+//   sans-serif   Inter          15px/23px
+//   serif        Georgia        14px/24px
+//   mono         ui-monospace   14px/24px
+//   rounded      Nunito         14px/24px
+//
+// Registering the families (the first half of MPO-44) stopped the collapse to
+// -apple-system 14px/normal, but the era pin landed after it and moved `$body`
+// to 15/23 — so ten of eleven stops were left on a second ladder, and flipping
+// the knob resized the label by a pixel and moved its leading. Same defect
+// class as the one MPO-44 was filed for: the knob was still taking type off
+// the ramp, just more quietly.
+//
+// Three deliberate departures from `$body`, all upward and all LC-11:
+//
+//  1. Leading is floored per category — `flooredLineHeight` raises the era's
+//     value where the taper falls under the category's ratio, never lowers
+//     it. Only display steps move; every text step is `$body`'s own value.
+//  2. Tracking is 0, not Inter's curve. That curve is Inter-specific, and an
+//     empty table is not neutral: the class Tamagui emits for `$mono` does
+//     not declare `--f-letterSpacing-*`, so the value fell through to the
+//     `:root` Inter one and Georgia and Nunito rendered at Inter's −0.13px.
+//     There is no measured optical curve for these faces, so 0 is the honest
+//     value rather than a borrowed one.
+//  3. Weight is the era's (400 at every step). The previous default was 300,
+//     which is off the reference's label weight in the other direction.
+//
+// `$body` itself is untouched: it IS upstream's table under the pin, and
+// MPO-19 owns it. Its ratio dips below LC-11's 1.4 body floor from $11 up;
+// FontKnobStyles floors that scope on web, and correcting the table would
+// have to be argued on MPO-19, not smuggled in here.
 
 const TRACKING_A = -0.0223;
 const TRACKING_B = 0.185;
@@ -50,39 +86,16 @@ export function interTrackingPx(sizePx: number): number {
   return Math.round(interTrackingEm(sizePx) * sizePx * 100) / 100;
 }
 
-/** Body leading stays on the ramp: size + 10 (14 → 24). Never CSS `normal`. */
+/**
+ * Legacy `size + 10` leading. Kept for `createDefaultFont` callers that pass
+ * their own size table and therefore have no era leading to floor.
+ */
 export const BODY_LINE_HEIGHT_OFFSET = 10;
 
 export function bodyLineHeightPx(sizePx: number): number {
   return sizePx + BODY_LINE_HEIGHT_OFFSET;
 }
 
-// Mirrors @tamagui/font-inter's default size table (pinned 2.0.0-rc.41) so
-// tracking can be computed per size key. The fonts.spec.ts invariant test
-// (letterSpacing[k] === interTrackingPx(size[k]) on the BUILT font) catches
-// any upstream drift. `true` is the default size token — omit it and
-// fontFamily="$serif" falls back to the system face with line-height:normal.
-// Category fonts (not heading/body) stay on this transcribed ramp.
-export const bodyFontSizes: Record<string, number> = {
-  1: 11,
-  2: 12,
-  3: 13,
-  4: 14,
-  true: 14,
-  5: 16,
-  6: 18,
-  7: 20,
-  8: 23,
-  9: 30,
-  10: 46,
-  11: 55,
-  12: 62,
-  13: 72,
-  14: 92,
-  15: 114,
-  16: 134,
-};
-
 /**
  * A tamagui font table with Variables unwrapped and `$` prefixes stripped.
  * Upstream hands these back either raw or wrapped depending on where in the
@@ -108,11 +121,29 @@ function trackingFor(sizes: Record<string, number>): Record<string, number> {
   return Object.fromEntries(Object.entries(sizes).map(([key, px]) => [key, interTrackingPx(px)]));
 }
 
+/** Zero tracking for every key of a size table (LC-11, non-Inter faces). */
+function neutralTracking(sizes: Record<string, number>): Record<string, number> {
+  return Object.fromEntries(Object.keys(sizes).map((key) => [key, 0]));
+}
+
 const v5Body = defaultConfig.fonts.body;
 const v5Heading = defaultConfig.fonts.heading;
 const bodySizes = numbers(v5Body.size);
+const bodyLineHeights = numbers(v5Body.lineHeight);
+const bodyWeights = plain<string>(v5Body.weight);
 const headingSizes = numbers(v5Heading.size);
 
+/**
+ * The era's body size table. Exported under its historical name because
+ * `createDefaultFont` defaults to it, so a consumer-registered category font
+ * lands on the same ladder as the built-in ones instead of a private copy
+ * that drifts at the next pin (MPO-19 X8/X9).
+ */
+export const bodyFontSizes: Record<string, number> = bodySizes;
+
+/** The era's body leading, before any per-category floor. */
+export const bodyFontLineHeights: Record<string, number> = bodyLineHeights;
+
 /**
  * Inter faces the workspace ships. v5 heading weights are sparse — 600 up to
  * $5, 700 at $6–$8, 800 from $9 — and A4's reading of that is the point:
@@ -127,46 +158,45 @@ const interFaces = {
 } as const;
 
 /**
- * Concrete family stacks for each `headingFont`/`bodyFont` category.
- * Distinct first families so a text-node measurement cannot collapse three
- * stops onto one system fallback. Matches `packages/config/fonts.ts`
- * (serif/mono are explicit system aliases; the rest are shipped webfonts).
+ * Concrete family stacks for each `headingFont`/`bodyFont` category. Alias of
+ * the one table in `fontCategoryStacks.ts`, which `FontKnobStyles` also reads
+ * for its `--f-family` fallback — one stop cannot render two faces.
  */
-export const fontFamilyStacks = {
-  "sans-serif":
-    'Inter, -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
-  serif: "Georgia, 'Times New Roman', Times, serif",
-  mono: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
-  slab: "'Roboto Slab', 'Rockwell', 'Courier New', serif",
-  rounded: "'Nunito', 'Varela Round', system-ui, sans-serif",
-  condensed: "'Roboto Condensed', 'Arial Narrow', sans-serif",
-  cursive: "'Dancing Script', 'Pacifico', cursive",
-  handwriting: "'Caveat', 'Patrick Hand', 'Comic Sans MS', cursive",
-  pixel: "'Silkscreen', 'Press Start 2P', monospace",
-  blackletter: "'UnifrakturCook', 'Fraktur', serif",
-  geometric: "'Futura', 'Poppins', 'Century Gothic', sans-serif",
-} as const;
+export const fontFamilyStacks = fontCategoryStacks;
 
-export type FontFamilyCategory = keyof typeof fontFamilyStacks;
+export type FontFamilyCategory = FontCategory;
 
 /**
- * Category font on the body ramp: same size table as Inter (including
- * `true: 14`) and lineHeight size+10. Inter tracking is NOT copied — that
- * curve is Inter-specific (LC-11); FontKnobStyles applies per-category
- * floors when the knob restyles `$heading`/`$body`.
+ * Leading for one category: the era's body table with the category's LC-11
+ * floor applied. Every text step comes back as `$body`'s own value; only the
+ * display steps, where the era's taper eases below the floor, move up.
  */
-export function createCategoryFont(family: string): GenericFont {
-  return createInterFont(
-    {
-      family,
-      letterSpacing: {},
-    },
-    {
-      sizeLineHeight: bodyLineHeightPx,
-    },
+export function categoryLineHeights(category: FontCategory): Record<string, number> {
+  const minRatio = (fontCategoryMetrics[category] ?? fontCategoryMetrics["sans-serif"]).body;
+  return Object.fromEntries(
+    Object.entries(bodySizes).map(([key, px]) => [
+      key,
+      flooredLineHeight(px, bodyLineHeights[key] ?? bodyLineHeightPx(px), minRatio),
+    ]),
   );
 }
 
+/**
+ * Category font on the `$body` ladder: same sizes (including `true`), same
+ * weights, leading floored per LC-11, tracking neutral. A missing `true` key
+ * is what collapsed `$serif`/`$mono`/`$rounded` to the system face at
+ * `line-height: normal` (MPO-44).
+ */
+export function createCategoryFont(category: FontCategory, family: string): GenericFont {
+  return createFont({
+    family,
+    size: bodySizes,
+    lineHeight: categoryLineHeights(category),
+    weight: bodyWeights,
+    letterSpacing: neutralTracking(bodySizes),
+  }) as GenericFont;
+}
+
 export const defaultHeadingFont = createInterFont(
   {
     face: interFaces,
@@ -182,23 +212,29 @@ export const defaultBodyFont = createInterFont(
   {
     face: interFaces,
     size: bodySizes,
-    lineHeight: numbers(v5Body.lineHeight),
-    weight: plain<string>(v5Body.weight),
+    lineHeight: bodyLineHeights,
+    weight: bodyWeights,
     letterSpacing: trackingFor(bodySizes),
   },
   { sizeSize: (size) => size },
 );
 
-export const defaultSerifFont = createCategoryFont(fontFamilyStacks.serif);
-export const defaultMonoFont = createCategoryFont(fontFamilyStacks.mono);
-export const defaultSlabFont = createCategoryFont(fontFamilyStacks.slab);
-export const defaultRoundedFont = createCategoryFont(fontFamilyStacks.rounded);
-export const defaultCondensedFont = createCategoryFont(fontFamilyStacks.condensed);
-export const defaultCursiveFont = createCategoryFont(fontFamilyStacks.cursive);
-export const defaultHandwritingFont = createCategoryFont(fontFamilyStacks.handwriting);
-export const defaultPixelFont = createCategoryFont(fontFamilyStacks.pixel);
-export const defaultBlackletterFont = createCategoryFont(fontFamilyStacks.blackletter);
-export const defaultGeometricFont = createCategoryFont(fontFamilyStacks.geometric);
+export const defaultSerifFont = createCategoryFont("serif", fontFamilyStacks.serif);
+export const defaultMonoFont = createCategoryFont("mono", fontFamilyStacks.mono);
+export const defaultSlabFont = createCategoryFont("slab", fontFamilyStacks.slab);
+export const defaultRoundedFont = createCategoryFont("rounded", fontFamilyStacks.rounded);
+export const defaultCondensedFont = createCategoryFont("condensed", fontFamilyStacks.condensed);
+export const defaultCursiveFont = createCategoryFont("cursive", fontFamilyStacks.cursive);
+export const defaultHandwritingFont = createCategoryFont(
+  "handwriting",
+  fontFamilyStacks.handwriting,
+);
+export const defaultPixelFont = createCategoryFont("pixel", fontFamilyStacks.pixel);
+export const defaultBlackletterFont = createCategoryFont(
+  "blackletter",
+  fontFamilyStacks.blackletter,
+);
+export const defaultGeometricFont = createCategoryFont("geometric", fontFamilyStacks.geometric);
 
 /** All purpose + category fonts registered by `createDefaultThemeConfig`. */
 export const defaultFonts = {

package/src/theme/focusState.spec.ts

@@ -136,11 +136,22 @@ describe("$outlineColor token contrast (DF-03 / DG-A11Y-01)", () => {
   }
 
   it("the retired flat inset failed the floor over the solid intent fills (why offset is 0)", () => {
-    // The measured failures that forced the flip (MPO-41 / MPO-19 X7): a −2
-    // band paints INSIDE the control, so it had to contrast against the solid
-    // intent fill — light accent 1.27:1, light error 1.17:1, dark error
-    // 1.31:1. Locking these <3:1 keeps the offset-0 geometry load-bearing: if
-    // the fills ever lighten past the floor this test goes stale, not wrong.
+    // The failures that forced the flip (MPO-41 / MPO-19 X7): a −2 band paints
+    // INSIDE the control, so it had to contrast against the solid intent fill.
+    //
+    // Provenance, because the two numbers are easy to conflate. The headline
+    // figures — light accent 1.27:1, light error 1.17:1, dark error 1.31:1 —
+    // are RENDERED measurements off the action-and-feedback board at DPR 2,
+    // ring node against the Button's painted background. This test computes a
+    // DIFFERENT pair: the base `outlineColor` against the intent sub-theme's
+    // `color9` ink step (1.67 / 1.55 / 1.44 in this build). Same verdict, same
+    // reason, different surfaces — the board's error fills (#ce2c31 / #ff9794)
+    // are not in these default sub-theme ramps at all, so the fill side is the
+    // board's to own and not this package's.
+    //
+    // What this assertion IS: no sub-theme ink step the inset band could land
+    // on clears the floor, which keeps the offset-0 geometry load-bearing. If
+    // the ramps ever lighten past 3:1 this test goes stale, not wrong.
     for (const [scheme, intent] of [
       ["light", "accent"],
       ["light", "error"],
@@ -196,9 +207,7 @@ describe("LC-71: keyboard-only; measure the ring / text node, not the frame", ()
   });
 
   it("chip dismiss rings the glyph node, not the 44px hit-box frame", () => {
-    const frameRule = compositeFocusRingCss.match(
-      /\.mp-chip-dismiss:focus-visible\s*\{([^}]+)\}/,
-    );
+    const frameRule = compositeFocusRingCss.match(/\.mp-chip-dismiss:focus-visible\s*\{([^}]+)\}/);
     const ringRule = compositeFocusRingCss.match(
       /\.mp-chip-dismiss:focus-visible \.mp-chip-dismiss-ring\s*\{([^}]+)\}/,
     );

package/src/theme/fontCategoryMetrics.ts

@@ -0,0 +1,57 @@
+import type { FontCategory } from "./knobs";
+
+/**
+ * Per-category legibility floors (LC-11 FONT-FAMILY-METRICS).
+ *
+ * `heading` / `body` are minimum lineHeight:fontSize ratios. `letterSpacing:
+ * "neutral"` marks the families where Inter's tracking-by-size curve is
+ * actively wrong — fixed-pitch faces must keep their pitch, and connected
+ * scripts break when tracked apart.
+ *
+ * Two consumers read this table and they must never drift apart:
+ *
+ *  - `FontKnobStyles` emits `--f-lineHeight-N` overrides on the `.font_body`
+ *    / `.font_heading` CSS scopes, which is how the knob restyles text that
+ *    never asked for a category token (web only).
+ *  - `defaults/fonts.ts` bakes the same floors into each registered category
+ *    font's own lineHeight table, which is the path the knob actually takes:
+ *    `bodyFont: "serif"` renders `.font_serif`, and the CSS scope rules above
+ *    are keyed to `.font_body`, so they never reach it. Native has no CSS at
+ *    all and depends on the table entirely.
+ *
+ * "sans-serif" is the default scope and is listed for completeness — the
+ * `$body` / `$heading` tables are upstream's under the v5 era pin (MPO-19
+ * X8/X9) and this file does not rewrite them.
+ */
+export const fontCategoryMetrics: Record<
+  FontCategory,
+  { heading: number; body: number; letterSpacing: "inherit" | "neutral" }
+> = {
+  "sans-serif": { heading: 1.15, body: 1.4, letterSpacing: "inherit" },
+  serif: { heading: 1.2, body: 1.4, letterSpacing: "inherit" },
+  mono: { heading: 1.25, body: 1.45, letterSpacing: "neutral" },
+  // Heading floors below are sized to each configured face's em box
+  // (ascent+descent) so display headings never clip (LC-11): Roboto Slab
+  // ≈1.32, Nunito ≈1.36, Silkscreen ≈1.3, Poppins/Futura ≈1.4.
+  slab: { heading: 1.35, body: 1.4, letterSpacing: "inherit" },
+  rounded: { heading: 1.4, body: 1.4, letterSpacing: "inherit" },
+  condensed: { heading: 1.15, body: 1.4, letterSpacing: "inherit" },
+  cursive: { heading: 1.3, body: 1.5, letterSpacing: "neutral" },
+  handwriting: { heading: 1.25, body: 1.45, letterSpacing: "neutral" },
+  pixel: { heading: 1.35, body: 1.4, letterSpacing: "neutral" },
+  blackletter: { heading: 1.3, body: 1.45, letterSpacing: "neutral" },
+  geometric: { heading: 1.45, body: 1.4, letterSpacing: "inherit" },
+};
+
+/**
+ * Leading for one size step: the era's own value, raised to the category's
+ * floor when the era's taper falls under it. Never below the base, so a
+ * category can only ever ask for MORE room than `$body` takes, never less.
+ */
+export function flooredLineHeight(
+  sizePx: number,
+  baseLineHeightPx: number,
+  minRatio: number,
+): number {
+  return Math.max(baseLineHeightPx, Math.round(sizePx * minRatio));
+}

package/src/theme/fontCategoryStacks.ts

@@ -1,18 +1,31 @@
 import type { FontCategory } from "./knobs";
 
 /**
- * Concrete stacks for each headingFont/bodyFont category. Used as the
- * FontKnobStyles `--f-family` fallback when Tamagui has no `$serif` (etc.)
- * font registered, and as the default category fonts on
- * createDefaultThemeConfig so consumers do not have to pass a font map.
+ * The one concrete family stack per headingFont/bodyFont category.
  *
- * Matches packages/config/fonts.ts (system serif/mono; webfonts for the rest).
+ * Both paths read THIS table, so a stop cannot render one face through the
+ * registered font and another through the CSS fallback:
+ *
+ *  - `defaults/fonts.ts` builds the registered `$serif` / `$mono` / … fonts
+ *    from it (the path the knob takes on every platform).
+ *  - `FontKnobStyles` falls back to it for `--f-family` when a consumer's
+ *    config has no font registered for the category (live SHC console had
+ *    the style tag and skipped the family).
+ *
+ * Distinct FIRST families throughout, because a text-node measurement reads
+ * the first resolvable name — three stops that all begin at a system
+ * fallback is the MPO-44 defect.
+ *
+ * Tracks `packages/config/fonts.ts` (serif/mono/geometric are system aliases,
+ * the rest are shipped webfonts). `mono` is the one deliberate widening: the
+ * template's bare `monospace` keyword leaves the face to the UA, so this
+ * names the platform faces ahead of it and keeps the keyword last.
  */
 export const fontCategoryStacks: Record<FontCategory, string> = {
   "sans-serif":
     'Inter, -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
   serif: "Georgia, 'Times New Roman', Times, serif",
-  mono: "monospace",
+  mono: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
   slab: "'Roboto Slab', 'Rockwell', 'Courier New', serif",
   rounded: "'Nunito', 'Varela Round', system-ui, sans-serif",
   condensed: "'Roboto Condensed', 'Arial Narrow', sans-serif",

package/src/theme/index.ts

@@ -9,6 +9,7 @@ export * from "./defaults/index";
 export * from "./devtools/ThemeDevtoolsPanel";
 export * from "./focusState";
 export * from "./glyphPaint";
+export * from "./fontCategoryMetrics";
 export * from "./fontCategoryStacks";
 export * from "./FontKnobStyles";
 export * from "./groupGeometry";

package/src/theme/resolveKnobs.spec.ts

@@ -1,3 +1,4 @@
+import { tokens } from "@tamagui/themes";
 import { describe, expect, it, vi } from "vitest";
 import {
   defaultKnobs,
@@ -580,8 +581,7 @@ describe("resolveKnobs", () => {
       ).toBe("$6");
     });
 
-    it("mirrored px values agree with the live @tamagui/themes tokens (drift guard)", async () => {
-      const { tokens } = await import("@tamagui/themes");
+    it("mirrored px values agree with the live @tamagui/themes tokens (drift guard)", () => {
       const radiusTokenByKnob = {
         none: "$0",
         small: "$2",
@@ -1133,6 +1133,20 @@ describe("applyDensity", () => {
     expect(compact.knobProps.control.paddingHorizontal).toBe(16);
   });
 
+  it("names which gap density moves: the LAYOUT gap, never the recipe gap (LC-79)", () => {
+    // `control.gap` tracks the RADIUS knob, so it is invariant under density
+    // by construction. The gap a reader sees tighten is `knobProps.gap`, the
+    // space-ramp one, and it only moves once `applyDensity` has stepped
+    // `space` — `resolveKnobs` alone is a pure token mapper.
+    const comfortable = resolveKnobs(applyDensity(knobsWith({ space: "medium" })));
+    const compact = resolveKnobs(applyDensity(knobsWith({ space: "medium", density: "compact" })));
+    expect(compact.knobProps.control.gap).toBe(comfortable.knobProps.control.gap);
+    expect(compact.knobProps.gap).not.toEqual(comfortable.knobProps.gap);
+    expect(compact.knobProps.panelPadding).not.toEqual(comfortable.knobProps.panelPadding);
+    expect(compact.knobProps.control.height).toBe(44);
+    expect(comfortable.knobProps.control.height).toBe(44);
+  });
+
   it("compact density produces the same sizeToken and a smaller gap than comfortable", () => {
     const comfortable = resolveKnobs(applyDensity(knobsWith({ size: "medium", space: "medium" })));
     const compact = resolveKnobs(

package/src/theme/resolveKnobs.ts

@@ -97,8 +97,9 @@ const borderWidthMap = {
 // ── Corner smoothing (Axiom 15 OPTICS) ────────────────────────
 // `smooth` upgrades circular-arc corners to continuous curvature —
 // `corner-shape: squircle` (≡ superellipse(2), ≈ Apple / Figma 0.6) — as a
-// web progressive enhancement: Chromium 139+ paints it, every other engine
-// drops the unknown declaration and keeps the plain border-radius arc.
+// web progressive enhancement: Chromium paints it (measured from 143; WebKit
+// 26 and Firefox 148 drop the unknown declaration and keep the plain
+// border-radius arc — docs/design/boards/W1-corner-smoothing/).
 // Delivery is a class + mounted stylesheet (cornerSmoothing.ts) because
 // Tamagui strips unknown keys from the `style` prop (skipProps) but merges
 // `className`. Native resolves to `round` for now (SquircleView adoption is

package/types/audit/index.d.ts

@@ -2,4 +2,6 @@ export type { AuditReport, AuditSummary, ElementAudit, PropertyAudit, TextProper
 export { runConstraintAudit } from "./constraintAudit";
 export type { AuditDiff, ElementDiff, PropertyDiff } from "./diffReport";
 export { diffAuditReports, formatAuditReport } from "./diffReport";
+export type { GeometryDiff, GeometryMove, MatrixElementGeometry, MatrixRect, MatrixSnapshot, MatrixTextSample, NoBreakageInput, NoBreakageResult, TextContrastResult, TextContrastViolation, } from "./themeMatrix";
+export { auditSignatures, captureMatrixSnapshot, diffGeometry, evaluateNoBreakage, evaluateTextContrast, } from "./themeMatrix";
 //# sourceMappingURL=index.d.ts.map

package/types/audit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}