@multiplatform.one/theme 7.4.0 → 7.5.0

package/src/theme/defaults/fonts.ts

@@ -1,12 +1,26 @@
+import { defaultConfig } from "@tamagui/config/v5";
 import { createInterFont } from "@tamagui/font-inter";
+import type { GenericFont } from "tamagui";
 
 // 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,
@@ -16,6 +30,11 @@ import { createInterFont } from "@tamagui/font-inter";
 // 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).
 
 const TRACKING_A = -0.0223;
 const TRACKING_B = 0.185;
@@ -31,11 +50,20 @@ 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`. */
+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.
-const interBaseSizes: Record<string, number> = {
+// 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,
@@ -55,35 +83,135 @@ const interBaseSizes: Record<string, number> = {
   16: 134,
 };
 
-function trackingTable(scaleSize: (size: number) => number): Record<string, number> {
-  return Object.fromEntries(
-    Object.entries(interBaseSizes).map(([key, size]) => [key, interTrackingPx(scaleSize(size))]),
-  );
+/**
+ * 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;
 }
 
-const headingSizeOf = (size: number) => Math.round(size * 1.4);
+/** A tamagui font table's numbers, with Variables and `$` prefixes unwrapped. */
+const numbers = (raw: unknown) => plain<number>(raw);
 
-export const defaultHeadingFont = createInterFont(
-  {
-    face: {
-      700: { normal: "InterBold" },
+/** 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)]));
+}
+
+const v5Body = defaultConfig.fonts.body;
+const v5Heading = defaultConfig.fonts.heading;
+const bodySizes = numbers(v5Body.size);
+const headingSizes = numbers(v5Heading.size);
+
+/**
+ * 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.
+ * 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).
+ */
+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 type FontFamilyCategory = keyof typeof fontFamilyStacks;
+
+/**
+ * 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`.
+ */
+export function createCategoryFont(family: string): GenericFont {
+  return createInterFont(
+    {
+      family,
+      letterSpacing: {},
     },
-    letterSpacing: trackingTable(headingSizeOf),
-  },
+    {
+      sizeLineHeight: bodyLineHeightPx,
+    },
+  );
+}
+
+export const defaultHeadingFont = createInterFont(
   {
-    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: numbers(v5Body.lineHeight),
+    weight: plain<string>(v5Body.weight),
+    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);
+
+/** 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,110 @@ 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 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.
+    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/fontCategoryStacks.ts

@@ -0,0 +1,24 @@
+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.
+ *
+ * Matches packages/config/fonts.ts (system serif/mono; webfonts for the rest).
+ */
+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",
+  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; }");

package/src/theme/glyphPaint.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { resolveGlyphPaint } from "./glyphPaint";
+
+describe("resolveGlyphPaint (LC-84)", () => {
+  it("never returns undefined", () => {
+    expect(resolveGlyphPaint({})).toBe("currentColor");
+    expect(resolveGlyphPaint({}, undefined)).toBe("currentColor");
+    expect(resolveGlyphPaint({}, null)).toBe("currentColor");
+    expect(resolveGlyphPaint({}, "")).toBe("currentColor");
+    expect(resolveGlyphPaint({ color: {} })).toBe("currentColor");
+  });
+
+  it("reads .val, never a missing get(web) path", () => {
+    expect(resolveGlyphPaint({ color: { val: "#fafafa" } })).toBe("#fafafa");
+    expect(resolveGlyphPaint({ color10: { val: "#abcabc" } }, "$color10")).toBe("#abcabc");
+    expect(resolveGlyphPaint({ placeholderColor: { val: "#888" } }, "placeholderColor")).toBe(
+      "#888",
+    );
+  });
+
+  it("passes through already-resolved colors and falls back to ink", () => {
+    expect(resolveGlyphPaint({ color: { val: "#111" } }, "#ff00aa")).toBe("#ff00aa");
+    expect(resolveGlyphPaint({ color12: { val: "#eee" } })).toBe("#eee");
+    expect(resolveGlyphPaint({ color11: { val: "#ddd" } })).toBe("#ddd");
+  });
+});

package/src/theme/glyphPaint.ts

@@ -0,0 +1,46 @@
+import { useTheme } from "tamagui";
+
+type ThemeToken = { val?: unknown };
+
+/**
+ * LC-84 — resolve a concrete glyph paint from a Tamagui theme token.
+ * Phosphor (and any SVG that defaults to `#000` / `currentColor` without a
+ * parent color) MUST receive this, never `theme.x.get("web")` which is
+ * undefined off-web and leaves the glyph black in dark mode.
+ *
+ * Never returns undefined.
+ */
+export function resolveGlyphPaint(
+  theme: Record<string, ThemeToken | undefined>,
+  color?: string | null,
+): string {
+  const seen = new Set<string>();
+  const push = (value: unknown) => {
+    if (typeof value === "string" && value.length > 0 && value !== "undefined") {
+      seen.add(value);
+    }
+  };
+
+  if (typeof color === "string" && color.length > 0) {
+    const key = color.startsWith("$") ? color.slice(1) : color;
+    push(theme[key]?.val);
+    if (color.startsWith("#") || color.startsWith("rgb") || color.startsWith("hsl")) {
+      push(color);
+    } else if (!theme[key]) {
+      push(color);
+    }
+  }
+
+  push(theme.color?.val);
+  push(theme.color12?.val);
+  push(theme.color11?.val);
+
+  for (const value of seen) return value;
+  return "currentColor";
+}
+
+/** Live theme ink for Phosphor / SVG carets (LC-84). Never undefined. */
+export function useGlyphColor(color?: string): string {
+  const theme = useTheme() as unknown as Record<string, ThemeToken | undefined>;
+  return resolveGlyphPaint(theme, color);
+}

package/src/theme/index.ts

@@ -8,6 +8,8 @@ export * from "./createThemes";
 export * from "./defaults/index";
 export * from "./devtools/ThemeDevtoolsPanel";
 export * from "./focusState";
+export * from "./glyphPaint";
+export * from "./fontCategoryStacks";
 export * from "./FontKnobStyles";
 export * from "./groupGeometry";
 export * from "./hairline";
@@ -20,6 +22,7 @@ export type { Preset as PresetDefinition, IntentOverride } from "./preset.types"
 export * from "./PresetContext";
 export * from "./presets";
 export * from "./radiusClass";
+export * from "./radiusClassTable.generated";
 export * from "./readableColor";
 export * from "./recipes";
 export * from "./resolveKnobs";

package/src/theme/knobs.ts

@@ -1,7 +1,16 @@
 // ── Structure ──────────────────────────────────────────────
 
+/** Structural fill. Exactly two values (R9 G9): `filled` | `outlined`. Ghost is a Chip/Tag variant, not this knob. */
 export const FillStyle = { Filled: "filled", Outlined: "outlined" } as const;
 export type FillStyle = (typeof FillStyle)[keyof typeof FillStyle];
+/** R9 G9 — adding a third FillStyle member fails this lock. */
+type _FillStyleExactlyTwo = FillStyle extends "filled" | "outlined"
+  ? "filled" | "outlined" extends FillStyle
+    ? true
+    : never
+  : never;
+const _fillStyleExactlyTwo: _FillStyleExactlyTwo = true;
+void _fillStyleExactlyTwo;
 
 export const BorderRadius = {
   None: "none",
@@ -15,8 +24,10 @@ export type BorderRadius = (typeof BorderRadius)[keyof typeof BorderRadius];
 /**
  * Corner curvature continuity (Axiom 15 OPTICS). `smooth` renders
  * continuous-curvature (superellipse/squircle) corners where the platform
- * can (web: Chromium 139+ via `corner-shape`, others fall back to the plain
- * arc); `round` is today's circular-arc border-radius everywhere.
+ * can (web: `corner-shape: squircle`, computed `superellipse(2)` on
+ * Chromium 152; engines without the property drop the declaration — that
+ * fallback is measured via `cssSupportsCornerShape`, not assumed); `round`
+ * is today's circular-arc border-radius everywhere.
  * Two values, not a numeric dial: every shipped smoothing system converges
  * on one blessed curve (Apple ≈ Figma 0.6 ≈ superellipse K=2), and a free
  * number invites per-screen drift (Axiom 5). `none` is not needed —
@@ -226,6 +237,11 @@ export type InteractionState = (typeof interactionStates)[number];
 
 export interface Knobs {
   fillStyle: FillStyle;
+  /**
+   * Per-role radius (MPO-21 R9): leftover radius maps onto DEFAULT /
+   * CIRCULAR-AT-FULL / BINARY / CONTAINER-CAP. No improvised radius prop
+   * and no fifth class on this interface.
+   */
   borderRadius: BorderRadius;
   /**
    * Corner curvature continuity (Axiom 15 OPTICS). Optional so existing

package/src/theme/layoutTokens.spec.ts

@@ -3,6 +3,7 @@ import {
   MIN_PRESS_TARGET,
   NARROW_BREAKPOINT,
   OVERLAY_ANCHOR_GAP,
+  OVERLAY_ATTACH_GAP,
   OVERLAY_BREAKPOINT,
   READING_WIDTH_CH,
   READING_WIDTH_MAX_CH,
@@ -69,8 +70,9 @@ describe("readingWidthStyle (DG-LAY-05)", () => {
 });
 
 describe("overlay anchoring", () => {
-  it("pins the shared trigger↔overlay gap at 4px", () => {
+  it("pins the free-overlay gap at 4px and the attach gap at 0", () => {
     expect(OVERLAY_ANCHOR_GAP).toBe(4);
+    expect(OVERLAY_ATTACH_GAP).toBe(0);
   });
 });