@multiplatform.one/theme 7.4.1 → 7.6.0

package/src/theme/defaults/fonts.ts

@@ -1,21 +1,76 @@
+import { defaultConfig } from "@tamagui/config/v5";
 import { createInterFont } from "@tamagui/font-inter";
+// `@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.
-// Tables match @tamagui/config/v4 (the scale Bento is authored against):
-// headings 1.4x the base size scale (H1 $10 = 64px, H2 $9 = 42, H3 $8 = 32,
-// H4 $7 = 28) at default weight with zero tracking — large and light, not
-// small and bold — and body at the unscaled 14px/$true with lineHeight
-// size+10. No uppercase transforms.
+//
+// MPO-19 X8 + X9. These tables used to be @tamagui/config/v4's — headings on a
+// 1.4x scale (H1 $10 = 64px) at whatever weight the knob happened to default
+// to, body at 14px with `lineHeight = size + 10`. Against the v5 era this
+// package now pins (see `TAMAGUI_ERA` in createDefaultThemeConfig.ts) that is a
+// different typographic voice, not a variation on one: H1 was 64px/400 where
+// stock v5 is 40px/800, large and light against compact and heavy. And
+// `size + 10` is not a ratio at all — 1.91 at 11px, 1.22 at 46px — which is
+// why v5 replaced it with an explicit taper.
+//
+// So the tables are no longer transcribed. They are READ from
+// `defaultConfig.fonts`, which means the era pin is load-bearing rather than
+// decorative: re-point it and the type scale follows, and there is no local
+// copy that can drift from upstream between pins. That also retires the
+// hand-mirrored `interBaseSizes` table this file used to carry purely so
+// tracking could be computed per key — the size table it needed IS the one
+// upstream ships.
 //
 // Tracking-by-size (Axiom 15 OPTICS + LC-11): letter-spacing is a function
 // of the rendered size, not a constant — slightly loose at caption sizes,
 // 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 (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;
@@ -31,59 +86,168 @@ export function interTrackingPx(sizePx: number): number {
   return Math.round(interTrackingEm(sizePx) * sizePx * 100) / 100;
 }
 
-// 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.
-const interBaseSizes: 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,
-};
-
-function trackingTable(scaleSize: (size: number) => number): Record<string, number> {
+/**
+ * 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;
+}
+
+/**
+ * A tamagui font table with Variables unwrapped and `$` prefixes stripped.
+ * Upstream hands these back either raw or wrapped depending on where in the
+ * config pipeline they were read, and `createInterFont` wants them raw.
+ */
+function plain<T>(raw: unknown): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const [key, value] of Object.entries((raw ?? {}) as Record<string, T | { val?: T }>)) {
+    const unwrapped =
+      value && typeof value === "object" && "val" in value
+        ? (value as { val?: T }).val
+        : (value as T);
+    if (unwrapped !== undefined) out[key.replace(/^\$/, "")] = unwrapped;
+  }
+  return out;
+}
+
+/** A tamagui font table's numbers, with Variables and `$` prefixes unwrapped. */
+const numbers = (raw: unknown) => plain<number>(raw);
+
+/** Inter dynamic tracking for every key of a size table. */
+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:
+ * everything between inherits, so bold is rare and therefore means something.
+ * Each declared weight needs a face or the browser synthesises one.
+ */
+const interFaces = {
+  400: { normal: "Inter" },
+  600: { normal: "InterSemiBold" },
+  700: { normal: "InterBold" },
+  800: { normal: "InterExtraBold" },
+} as const;
+
+/**
+ * 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 = fontCategoryStacks;
+
+export type FontFamilyCategory = FontCategory;
+
+/**
+ * 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 categoryLineHeights(category: FontCategory): Record<string, number> {
+  const minRatio = (fontCategoryMetrics[category] ?? fontCategoryMetrics["sans-serif"]).body;
   return Object.fromEntries(
-    Object.entries(interBaseSizes).map(([key, size]) => [key, interTrackingPx(scaleSize(size))]),
+    Object.entries(bodySizes).map(([key, px]) => [
+      key,
+      flooredLineHeight(px, bodyLineHeights[key] ?? bodyLineHeightPx(px), minRatio),
+    ]),
   );
 }
 
-const headingSizeOf = (size: number) => Math.round(size * 1.4);
+/**
+ * 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: {
-      700: { normal: "InterBold" },
-    },
-    letterSpacing: trackingTable(headingSizeOf),
-  },
-  {
-    sizeSize: headingSizeOf,
-    sizeLineHeight: (size) => size + 10,
+    face: interFaces,
+    size: headingSizes,
+    lineHeight: numbers(v5Heading.lineHeight),
+    weight: plain<string>(v5Heading.weight),
+    letterSpacing: trackingFor(headingSizes),
   },
+  { sizeSize: (size) => size },
 );
 
 export const defaultBodyFont = createInterFont(
   {
-    face: {
-      700: { normal: "InterBold" },
-    },
-    letterSpacing: trackingTable((size) => size),
-  },
-  {
-    sizeLineHeight: (size) => size + 10,
+    face: interFaces,
+    size: bodySizes,
+    lineHeight: bodyLineHeights,
+    weight: bodyWeights,
+    letterSpacing: trackingFor(bodySizes),
   },
+  { sizeSize: (size) => size },
 );
+
+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 = {
+  heading: defaultHeadingFont,
+  body: defaultBodyFont,
+  serif: defaultSerifFont,
+  mono: defaultMonoFont,
+  slab: defaultSlabFont,
+  rounded: defaultRoundedFont,
+  condensed: defaultCondensedFont,
+  cursive: defaultCursiveFont,
+  handwriting: defaultHandwritingFont,
+  pixel: defaultPixelFont,
+  blackletter: defaultBlackletterFont,
+  geometric: defaultGeometricFont,
+} as const;

package/src/theme/defaults/index.ts

@@ -1,4 +1,5 @@
 export * from "./accent";
 export * from "./base";
 export * from "./builderOptions";
+export * from "./categoryFonts";
 export * from "./fonts";

package/src/theme/devtools/ThemeDevtoolsPanel.tsx

@@ -1170,15 +1170,6 @@ export function ThemeDevtoolsPanel({
         }
       }
     }
-    const fill = partial.fillStyle ?? knobs.fillStyle;
-    const borderWidth = partial.borderWidth ?? knobs.borderWidth;
-    if (fill === "outlined" && borderWidth === "none") {
-      if (!pinnedKnobs.has("borderWidth")) {
-        partial.borderWidth = pick(["small", "medium", "large"] as const);
-      } else {
-        partial.fillStyle = "filled";
-      }
-    }
     setOverrides(newOverrides);
     setKnobs(partial);
     if (!pinnedKnobs.has("color") && themeColors && onThemeColorChange) {
@@ -1200,8 +1191,6 @@ export function ThemeDevtoolsPanel({
     expandedKnobs,
     activeProfile,
     animationOptions,
-    knobs.fillStyle,
-    knobs.borderWidth,
   ]);
 
   // -------------------------------------------------------------------------

package/src/theme/focusState.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { __resetDevWarnSeen, warnOutlineNone, warnPositiveTabIndex } from "../devWarn";
+import { compositeFocusRingCss, keyboardFocusRingProps } from "../keyboardFocusRing";
 import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
 import { createThemesBuilder } from "./createThemes";
 import { defaultAccentTheme } from "./defaults/accent";
@@ -11,6 +12,7 @@ import {
   FOCUS_RING_MIN_CONTRAST,
   FOCUS_RING_MIN_WIDTH,
   FOCUS_VISIBLE_RING,
+  FOCUS_VISIBLE_RING_INSET,
   STATE_LAYER_HOVER,
   STATE_LAYER_PRESS,
   withDefaultStateLayer,
@@ -19,10 +21,13 @@ import { defaultKnobs } from "./knobs";
 import { resolveKnobs } from "./resolveKnobs";
 
 describe("focusState tokens (DG-A11Y-01 / DG-STATE-01 / W12)", () => {
-  it("FOCUS_VISIBLE_RING meets ≥2px solid outline contract", () => {
+  it("FOCUS_VISIBLE_RING meets ≥2px solid outline contract at offset 0 (F1)", () => {
     expect(FOCUS_VISIBLE_RING.outlineWidth).toBeGreaterThanOrEqual(FOCUS_RING_MIN_WIDTH);
     expect(FOCUS_VISIBLE_RING.outlineStyle).toBe("solid");
     expect(FOCUS_VISIBLE_RING.outlineColor).toBe("$outlineColor");
+    // Board verify pass F1: offset 0 — not −2 (band inside the fill, where it
+    // measured 1.17–1.31:1 on solid intents) and not +2 (a gapped halo).
+    expect(FOCUS_VISIBLE_RING.outlineOffset).toBe(0);
     expect(FOCUS_RING_MIN_CONTRAST).toBeGreaterThanOrEqual(3);
   });
 
@@ -107,6 +112,119 @@ describe("$outlineColor token contrast (DF-03 / DG-A11Y-01)", () => {
       expect(Math.min(c1, c2)).toBeGreaterThanOrEqual(FOCUS_RING_MIN_CONTRAST);
     });
   }
+
+  // MPO-41 — assert the RATIO on the surface the band actually draws on, not
+  // just the declaration. At offset 0 the band paints OUTSIDE the border box,
+  // on the page ground behind the control; intent Buttons pin the parent-scope
+  // `$outlineColor` literal on the ring (LC-51), so the pair that must clear
+  // the floor is base `outlineColor` × base ground — for accent and error
+  // controls alike, in both schemes.
+  for (const scheme of ["light", "dark"] as const) {
+    for (const intent of ["accent", "error"] as const) {
+      it(`${scheme} ${intent}: offset-0 ring clears ≥3:1 on the page ground it draws on`, () => {
+        const base = themes[scheme];
+        expect(themes[`${scheme}_${intent}`]).toBeTruthy();
+        const ring = normalizeToHex(base.outlineColor);
+        const ground = normalizeToHex(base.color1);
+        expect(ring).toBeTruthy();
+        expect(ground).toBeTruthy();
+        expect(
+          contrastRatio(relativeLuminance(ring!), relativeLuminance(ground!)),
+        ).toBeGreaterThanOrEqual(FOCUS_RING_MIN_CONTRAST);
+      });
+    }
+  }
+
+  it("the retired flat inset failed the floor over the solid intent fills (why offset is 0)", () => {
+    // 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"],
+      ["dark", "error"],
+    ] as const) {
+      const ring = normalizeToHex(themes[scheme].outlineColor);
+      const fill = normalizeToHex(themes[`${scheme}_${intent}`].color9);
+      expect(ring).toBeTruthy();
+      expect(fill).toBeTruthy();
+      expect(contrastRatio(relativeLuminance(ring!), relativeLuminance(fill!))).toBeLessThan(
+        FOCUS_RING_MIN_CONTRAST,
+      );
+    }
+  });
+});
+
+describe("the ring still paints inside a clipped / fused group (LC-71 §4 inset carve-out)", () => {
+  it("FOCUS_VISIBLE_RING_INSET is the same ring pulled fully inside the border box", () => {
+    expect(FOCUS_VISIBLE_RING_INSET).toMatchObject({
+      outlineWidth: FOCUS_RING_MIN_WIDTH,
+      outlineStyle: "solid",
+      outlineColor: "$outlineColor",
+      outlineOffset: -2,
+    });
+    // The band spans [outlineOffset, outlineOffset + outlineWidth] from the
+    // border edge. Outer edge ≤ 0 means a clipping ancestor (fused group
+    // clipped at the group radius, menu overlay, table frame — LC-72
+    // CONTAINER-CLIP) cannot sever any part of it.
+    expect(
+      FOCUS_VISIBLE_RING_INSET.outlineOffset + FOCUS_VISIBLE_RING_INSET.outlineWidth,
+    ).toBeLessThanOrEqual(0);
+  });
+
+  it("keyboardFocusRingProps — the manual ring for roving-focus composites — pins the inset", () => {
+    expect(keyboardFocusRingProps).toEqual(FOCUS_VISIBLE_RING_INSET);
+  });
+
+  it("ensureFocusVisibleRing honors the explicit per-call-site inset and defaults to 0", () => {
+    expect(ensureFocusVisibleRing({ outlineOffset: -2 }).outlineOffset).toBe(-2);
+    expect(ensureFocusVisibleRing({ outlineWidth: 3 }).outlineOffset).toBe(0);
+    expect(ensureFocusVisibleRing().outlineOffset).toBe(0);
+  });
+});
+
+describe("LC-71: keyboard-only; measure the ring / text node, not the frame", () => {
+  it("standalone ring paints a 2px band on the ring-carrying node's box at offset 0", () => {
+    // Measure the node that paints the outline (the ring carrier / text node),
+    // never an ancestor Frame. Band = [offset, offset + width] from THAT box.
+    const { outlineOffset, outlineWidth } = FOCUS_VISIBLE_RING;
+    expect(outlineWidth).toBe(2);
+    expect(outlineOffset).toBe(0);
+    expect(outlineOffset + outlineWidth).toBe(2);
+  });
+
+  it("chip dismiss rings the glyph node, not the 44px hit-box frame", () => {
+    const frameRule = compositeFocusRingCss.match(/\.mp-chip-dismiss:focus-visible\s*\{([^}]+)\}/);
+    const ringRule = compositeFocusRingCss.match(
+      /\.mp-chip-dismiss:focus-visible \.mp-chip-dismiss-ring\s*\{([^}]+)\}/,
+    );
+    expect(frameRule?.[1]).toMatch(/outline:\s*none/);
+    expect(ringRule?.[1]).toMatch(/outline:\s*2px\s+solid/);
+    expect(ringRule?.[1]).toMatch(/outline-offset:\s*0/);
+    expect(ringRule?.[1]).not.toMatch(/outline-offset:\s*2px/);
+  });
+
+  it("non-text composites ring on :focus-visible only; text-entry keeps the any-focus carve-out", () => {
+    expect(compositeFocusRingCss).toMatch(/\.mp-composite-ring:focus-visible/);
+    expect(compositeFocusRingCss).toMatch(/\.mp-composite-ring-deep:has\(:focus-visible\)/);
+    expect(compositeFocusRingCss).toMatch(/\.mp-chip-dismiss:focus-visible/);
+    // Text-entry carve-out (LC-71 §1a): focusing an input means typing.
+    expect(compositeFocusRingCss).toMatch(/:has\(input:focus\)/);
+    expect(compositeFocusRingCss).toMatch(/:has\(textarea:focus\)/);
+  });
 });
 
 describe("resolveKnobs control recipes (W12)", () => {

package/src/theme/focusState.ts

@@ -47,18 +47,43 @@ export function focusRingColorMeetsContrast(ringColor: string, surfaceColor: str
 }
 
 /**
- * ONE ring geometry (DG-A11Y-01): 2px solid `$outlineColor`, inset −2.
- * Inset is the only offset that survives fused/clipped groups (segmented
- * controls clip children at the group radius; an outset ring paints square
- * across the clip or disappears under `overflow: hidden`) and it matches
- * `keyboardFocusRingProps`, the manual ring painted for roving-focus
- * widgets — so keyboard focus reads identically everywhere.
+ * ONE ring geometry (DG-A11Y-01 / LC-71 §4): 2px solid `$outlineColor` at
+ * offset **0** — the band hugs the border box and paints OUTSIDE it, on the
+ * surface behind the control (reference §10; board F1 verify pass: offset 0,
+ * not −2 and not +2). Offset 0 is what makes the ≥3:1 floor computable: the
+ * ring contrasts against the page ground, not the control's own fill. The
+ * old flat inset (−2) painted the band INSIDE solid intent fills and sank to
+ * 1.17–1.31:1 (light accent 1.27, light error 1.17, dark error 1.31) where
+ * the same ring on the page ground clears 5.78–6.50:1 (MPO-41 / MPO-19 X7).
+ *
+ * The inset did not die — it moved to `FOCUS_VISIBLE_RING_INSET`, an
+ * explicit per-call-site carve-out for clipping ancestors. MPO-19 X7 names
+ * the same offset `FOCUS_RING_CLIPPED_OFFSET` so call sites do not type `-2`.
  */
+export const FOCUS_RING_CLIPPED_OFFSET = -2;
 export const FOCUS_VISIBLE_RING = {
   outlineWidth: FOCUS_RING_MIN_WIDTH,
   outlineStyle: "solid" as const,
   outlineColor: "$outlineColor",
-  outlineOffset: -2,
+  outlineOffset: 0,
+} satisfies ControlStateProps;
+
+/**
+ * The LC-71 §4 clipping carve-out: the SAME ring, pulled fully inside the
+ * border box (offset −2 + width 2 ⇒ the band spans [−2, 0] from the edge, so
+ * no clipping ancestor can sever it). ONLY for items inside `overflow`
+ * clipping — fused/segmented groups clipped at the group radius, edge-to-edge
+ * menu rows under a clipped overlay (LC-72 CONTAINER-CLIP), table cells.
+ * Standalone controls take `FOCUS_VISIBLE_RING`; call sites opt into the
+ * inset explicitly (this constant, or
+ * `ensureFocusVisibleRing({ outlineOffset: -2 })`). Verification measures the
+ * painted composition, never the declared offset alone — a ring box inset
+ * from the boundary reports a compliant offset while painting inside it
+ * (the F1 pseudoInset trap, mpo-fields-measured.md §7).
+ */
+export const FOCUS_VISIBLE_RING_INSET = {
+  ...FOCUS_VISIBLE_RING,
+  outlineOffset: FOCUS_RING_CLIPPED_OFFSET,
 } satisfies ControlStateProps;
 
 /**

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

@@ -0,0 +1,37 @@
+import type { FontCategory } from "./knobs";
+
+/**
+ * The one concrete family stack per headingFont/bodyFont category.
+ *
+ * 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: "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",
+};

package/src/theme/fontKnobStyles.spec.ts

@@ -55,9 +55,22 @@ describe("buildFontKnobCss", () => {
     expect(css).toContain(":root .font_body { --f-family: monospace !important");
   });
 
-  it("skips the family override for unregistered fonts but keeps the category's default leading", () => {
+  it("emits a fallback --f-family when serif is not registered in Tamagui (live SHC)", () => {
+    // Live console 2026-08-29: #mp-font-knob-styles was present but had no
+    // --f-family because SHC never registers a `serif` font. The knob still
+    // has to write a family, or headingFont/bodyFont are a no-op on painted
+    // $heading/$body text. Georgia is a system face — no webfont required.
+    const css = buildFontKnobCss("serif", "sans-serif", resolveFamily, noTables);
+    expect(css).toContain(
+      ":root .font_heading { --f-family: Georgia, 'Times New Roman', Times, serif !important; }",
+    );
+    expect(css).toContain(":where(:root .font_heading) { line-height:");
+  });
+
+  it("emits a fallback --f-family for other unregistered categories and keeps the category leading", () => {
     const css = buildFontKnobCss("cursive", "cursive", resolveFamily, noTables);
-    expect(css).not.toContain("--f-family");
+    expect(css).toContain(":root .font_heading { --f-family:");
+    expect(css).toContain("cursive !important");
     // cursive heading floor 1.3 beats the 1.25 minimum; body max(1.5, 1.5)
     expect(css).toContain(":where(:root .font_heading) { line-height: 1.3; }");
     expect(css).toContain(":where(:root .font_body) { line-height: 1.5; }");