@multiplatform.one/theme 7.4.1 → 7.6.0

package/src/theme/resolveKnobs.spec.ts

@@ -1,7 +1,9 @@
+import { tokens } from "@tamagui/themes";
 import { describe, expect, it, vi } from "vitest";
 import {
   defaultKnobs,
   emptyStateKnobs,
+  FillStyle,
   Space,
   Size,
   Density,
@@ -39,9 +41,13 @@ function knobsWith(overrides: Partial<Knobs>): Knobs {
 
 const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "borderRadius",
+  "borderRadiusNested",
   "borderRadiusOuter",
   "containerRadius",
   "elevation",
+  "overlayElevation",
+  "elevationChrome",
+  "scheme",
   "surface",
   "cardSurface",
   "elevatedSurface",
@@ -222,6 +228,13 @@ describe("resolveKnobs", () => {
       expect(resolveKnobs(knobsWith({ elevation: "small" })).knobProps.elevation).toBe("$1");
     });
 
+    it("overlay elevation at small is $2, not the control $1 token", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ elevation: "small" }));
+      expect(knobProps.overlayElevation).toBe("$2");
+      expect(knobProps.elevatedSurface.elevation).toBe("$2");
+      expect(knobProps.elevatedSurface.elevation).not.toBe(knobProps.elevation);
+    });
+
     it('maps "medium" → "$2"', () => {
       expect(resolveKnobs(knobsWith({ elevation: "medium" })).knobProps.elevation).toBe("$2");
     });
@@ -229,6 +242,41 @@ describe("resolveKnobs", () => {
     it('maps "large" → "$4"', () => {
       expect(resolveKnobs(knobsWith({ elevation: "large" })).knobProps.elevation).toBe("$4");
     });
+
+    it("light scheme keeps overlay fill at $background and paints a black shadow", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ elevation: "large" }), undefined, "light");
+      expect(knobProps.scheme).toBe("light");
+      expect(knobProps.elevatedSurface.backgroundColor).toBe("$background");
+      expect(knobProps.cardSurface.backgroundColor).toBe("$background");
+      expect(knobProps.inputBackground).toBe("$background");
+      expect(knobProps.elevatedSurface.shadowColor).toBe("#000");
+      expect(knobProps.elevatedSurface.shadowOpacity).toBe(0.15);
+      expect(knobProps.elevationChrome.elevation).toBe(8);
+    });
+
+    it("dark scheme tints overlay/card/input up the existing ramp (LC-85)", () => {
+      const none = resolveKnobs(knobsWith({ elevation: "none" }), undefined, "dark");
+      const small = resolveKnobs(knobsWith({ elevation: "small" }), undefined, "dark");
+      const large = resolveKnobs(knobsWith({ elevation: "large" }), undefined, "dark");
+      expect(none.knobProps.elevatedSurface.backgroundColor).toBe("$background");
+      expect(small.knobProps.elevatedSurface.backgroundColor).toBe("$color2");
+      expect(large.knobProps.elevatedSurface.backgroundColor).toBe("$color4");
+      expect(large.knobProps.cardSurface.backgroundColor).toBe("$color4");
+      expect(large.knobProps.inputBackground).toBe("$color5");
+      expect(large.knobProps.elevatedSurface.shadowColor).toBe("$color12");
+      expect(large.knobProps.elevatedSurface.shadowOpacity).toBe(0.12);
+      expect(none.knobProps.elevationChrome).toEqual({});
+    });
+
+    it("dark outlined inputs stay transparent — tint is for filled surfaces", () => {
+      const { knobProps } = resolveKnobs(
+        knobsWith({ elevation: "large", fillStyle: "outlined" }),
+        undefined,
+        "dark",
+      );
+      expect(knobProps.inputBackground).toBe("transparent");
+      expect(knobProps.elevatedSurface.backgroundColor).toBe("$color4");
+    });
   });
 
   // ── elevation on NATIVE (SB-N-04) ──────────────────────────
@@ -251,10 +299,15 @@ describe("resolveKnobs", () => {
           knobsWith({ elevation: "small", hover: { elevation: "medium" } }),
         );
         expect(small.knobProps.elevation).toBe(20);
-        expect(small.knobProps.elevatedSurface.elevation).toBe(20);
+        expect(small.knobProps.overlayElevation).toBe(28);
+        expect(small.knobProps.elevatedSurface.elevation).toBe(28);
+        expect(small.knobProps.elevatedSurface.elevation).not.toBe(small.knobProps.elevation);
         expect(small.elevation.hoverKnobProps?.elevation).toBe(28);
         expect(resolveNative(knobsWith({ elevation: "medium" })).knobProps.elevation).toBe(28);
         expect(resolveNative(knobsWith({ elevation: "large" })).knobProps.elevation).toBe(44);
+        expect(
+          resolveNative(knobsWith({ elevation: "large" })).knobProps.elevationChrome.elevation,
+        ).toBe(8);
       } finally {
         vi.doUnmock("@multiplatform.one/platform");
         vi.resetModules();
@@ -424,7 +477,7 @@ describe("resolveKnobs", () => {
     it("cardSurface = bg + radius + panelPadding, no border/shadow", () => {
       const { knobProps } = resolveKnobs(defaultKnobs);
       expect(knobProps.cardSurface).toEqual({
-        backgroundColor: "$color1",
+        backgroundColor: "$background",
         borderRadius: "$4",
         padding: "$4",
       });
@@ -443,13 +496,27 @@ describe("resolveKnobs", () => {
       expect(knobProps.cardSurface.borderRadius).toBe("$6");
     });
 
-    it("elevatedSurface = surface + radius + elevation", () => {
+    it("elevatedSurface = surface + radius + overlay elevation + paint", () => {
       const { knobProps } = resolveKnobs(defaultKnobs);
-      expect(knobProps.elevatedSurface).toEqual({
-        ...knobProps.surface,
-        borderRadius: knobProps.borderRadius.borderRadius,
-        elevation: knobProps.elevation,
-      });
+      expect(knobProps.elevatedSurface.elevation).toBe(knobProps.overlayElevation);
+      expect(knobProps.elevatedSurface.elevation).not.toBe(knobProps.elevation);
+      expect(knobProps.elevatedSurface.backgroundColor).toBe(knobProps.surface.backgroundColor);
+      expect(knobProps.elevatedSurface.borderColor).toBe(knobProps.surface.borderColor);
+      expect(knobProps.elevatedSurface.borderWidth).toBe(knobProps.surface.borderWidth);
+      expect(knobProps.elevatedSurface.borderRadius).toBe(knobProps.borderRadius.borderRadius);
+    });
+
+    it("overlay elevation token differs from the control elevation token", () => {
+      for (const elevation of ["small", "medium", "large"] as const) {
+        const { knobProps } = resolveKnobs(knobsWith({ elevation }));
+        expect(knobProps.overlayElevation, elevation).toBeDefined();
+        expect(knobProps.overlayElevation, elevation).not.toBe(knobProps.elevation);
+        expect(knobProps.elevatedSurface.elevation, elevation).toBe(knobProps.overlayElevation);
+      }
+      const none = resolveKnobs(knobsWith({ elevation: "none" }));
+      expect(none.knobProps.elevation).toBeUndefined();
+      expect(none.knobProps.overlayElevation).toBeUndefined();
+      expect(none.knobProps.elevatedSurface.elevation).toBeUndefined();
     });
 
     it("featureSurface uses big radius, $6 padding, and an ultra-soft shadow", () => {
@@ -514,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",
@@ -543,7 +609,7 @@ describe("resolveKnobs", () => {
   describe("cornerSmoothing knob", () => {
     const radiusFragments = [
       "borderRadius",
-      "borderRadiusOuter",
+      "borderRadiusNested",
       "containerRadius",
       "cardSurface",
       "elevatedSurface",
@@ -585,7 +651,7 @@ describe("resolveKnobs", () => {
       );
       // $0 corners have no arc — square world stays square (Axiom 3 NULL).
       expect(knobProps.borderRadius).not.toHaveProperty("className");
-      expect(knobProps.borderRadiusOuter).not.toHaveProperty("className");
+      expect(knobProps.borderRadiusNested).not.toHaveProperty("className");
       expect(knobProps.containerRadius).not.toHaveProperty("className");
       expect(knobProps.cardSurface).not.toHaveProperty("className");
       expect(knobProps.elevatedSurface).not.toHaveProperty("className");
@@ -604,7 +670,7 @@ describe("resolveKnobs", () => {
       expect(knobProps.elevatedSurface).not.toHaveProperty("className");
       // Capped/outer fragments stay plain arcs (cap = padding px, outer ≤ $5)
       // and keep smoothing.
-      expect(knobProps.borderRadiusOuter.className).toBe(cornerSmoothClassName);
+      expect(knobProps.borderRadiusNested.className).toBe(cornerSmoothClassName);
       expect(knobProps.containerRadius.className).toBe(cornerSmoothClassName);
       expect(knobProps.cardSurface.className).toBe(cornerSmoothClassName);
       expect(knobProps.featureSurface.className).toBe(cornerSmoothClassName);
@@ -681,6 +747,54 @@ describe("resolveKnobs", () => {
       const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "outlined" }));
       expect(knobProps.outlined).toBe(true);
     });
+
+    it("union is filled | outlined only (R9 G9)", () => {
+      expect(Object.values(FillStyle)).toEqual(["filled", "outlined"]);
+      expect(Object.values(FillStyle)).toHaveLength(2);
+    });
+  });
+
+  describe("separator weight is not a knob (R9 G10)", () => {
+    it("Knobs has no separatorWeight channel", () => {
+      expect("separatorWeight" in defaultKnobs).toBe(false);
+      expect(Object.keys(defaultKnobs)).not.toContain("separatorWeight");
+    });
+  });
+
+  describe("fillStyle × borderWidth (LC-86 OUTLINED-HAIRLINE)", () => {
+    it("filled + none is chromeless (width 0)", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "filled", borderWidth: "none" }));
+      expect(knobProps.borderRadius.borderWidth).toBe(0);
+      expect(knobProps.surface.borderWidth).toBe(0);
+      expect(knobProps.elevatedSurface.borderWidth).toBe(0);
+      expect(knobProps.inputSurface.borderWidth).toBe(0);
+    });
+
+    it("outlined + none still draws the hairline (small stop, 0.5)", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "outlined", borderWidth: "none" }));
+      expect(knobProps.borderRadius.borderWidth).toBe(0.5);
+      expect(knobProps.surface.borderWidth).toBe(0.5);
+      expect(knobProps.elevatedSurface.borderWidth).toBe(0.5);
+      expect(knobProps.inputSurface.borderWidth).toBe(0.5);
+    });
+
+    it("outlined + small stays at the hairline, not a hidden 1px floor", () => {
+      const { knobProps } = resolveKnobs(
+        knobsWith({ fillStyle: "outlined", borderWidth: "small" }),
+      );
+      expect(knobProps.borderRadius.borderWidth).toBe(0.5);
+    });
+
+    it("outlined + medium/large keep the requested width", () => {
+      expect(
+        resolveKnobs(knobsWith({ fillStyle: "outlined", borderWidth: "medium" })).knobProps
+          .borderRadius.borderWidth,
+      ).toBe(1);
+      expect(
+        resolveKnobs(knobsWith({ fillStyle: "outlined", borderWidth: "large" })).knobProps
+          .borderRadius.borderWidth,
+      ).toBe(2);
+    });
   });
 
   // ── pointy ────────────────────────────────────────────────
@@ -1005,6 +1119,34 @@ describe("applyDensity", () => {
     expect(resolveKnobs(knobsWith({ density: "compact" })).knobProps.density).toBe("compact");
   });
 
+  it("compact and comfortable differ in padX while height stays 44 (LC-76)", () => {
+    const comfortable = resolveKnobs(knobsWith({ density: "comfortable" }));
+    const compact = resolveKnobs(knobsWith({ density: "compact" }));
+    expect(comfortable.knobProps.control.height).toBe(44);
+    expect(compact.knobProps.control.height).toBe(44);
+    expect(comfortable.knobProps.sizeToken).toBe("$4");
+    expect(compact.knobProps.sizeToken).toBe("$4");
+    expect(compact.knobProps.control.paddingHorizontal).not.toBe(
+      comfortable.knobProps.control.paddingHorizontal,
+    );
+    expect(comfortable.knobProps.control.paddingHorizontal).toBe(18);
+    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

@@ -9,11 +9,13 @@ import {
   STATE_LAYER_PRESS,
   withDefaultStateLayer,
 } from "./focusState";
-import type { CornerSmoothing, Knobs, PageTitleScale, StateKnobs } from "./knobs";
+import type { CornerSmoothing, Elevation, Knobs, PageTitleScale, StateKnobs } from "./knobs";
 import { pressTargetHitSlop } from "./layoutTokens";
 import type {
   ControlStateProps,
   DisabledRecipe,
+  ElevationChromeProps,
+  ElevationPaintProps,
   ElevationStateProps,
   KnobProps,
   KnobPropsOverride,
@@ -64,7 +66,7 @@ export function applyDensity(knobs: Knobs, compactOverride?: boolean): Knobs {
 
 // ── Knob-to-token mapping tables ──────────────────────────────
 
-const borderRadiusMap = {
+export const borderRadiusMap = {
   none: "$0",
   small: "$2",
   medium: "$4",
@@ -72,7 +74,12 @@ const borderRadiusMap = {
   full: "$12",
 } as const;
 
-const outerRadiusMap = {
+// Radius for chrome nested INSIDE a radius-bearing frame. Smaller than
+// `borderRadiusMap` at every stop that has room to be — a child corner equal
+// to its parent's reads as a second frame rather than as part of one.
+// MPO-19 X12: was `outerRadiusMap`, feeding a fragment called
+// `borderRadiusOuter` that every consumer used for inner chrome.
+const nestedRadiusMap = {
   none: "$0",
   small: "$2",
   medium: "$3",
@@ -90,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
@@ -243,10 +251,121 @@ const fontWeightMap = {
 // be cast to java.lang.Double" (SB-N-04). The numbers are the exact
 // tokens.size values Tamagui resolves those tokens to ($1=20, $2=28, $4=44),
 // so Tamagui consumers render identical shadows either way.
-const elevationMap: Record<string, string | number | undefined> = isWeb
+//
+// Control elevation ($1 at the default small stop) is the in-page Button
+// token. Overlay elevation is a DISTINCT token one step above that stop so
+// a dialog over a scrim and a Button on the page do not read as the same
+// distance off the surface (DG-OVL-01 / E-OVERLAY). elevatedSurface binds
+// the overlay token — not the control one.
+export const elevationMap: Record<string, string | number | undefined> = isWeb
   ? { none: undefined, small: "$1", medium: "$2", large: "$4" }
   : { none: undefined, small: 20, medium: 28, large: 44 };
 
+export const overlayElevationMap: Record<string, string | number | undefined> = isWeb
+  ? { none: undefined, small: "$2", medium: "$3", large: "$5" }
+  : { none: undefined, small: 28, medium: 36, large: 52 };
+
+/** Scheme the resolver was invoked with. Defaults light so unit tests stay stable. */
+export type ColorScheme = "light" | "dark";
+
+// Existing 12-step ramp (colorRules groups). Do not invent overlay tokens:
+// dark elevation is a lighter $color step. Overlay/card rest on $color1;
+// filled inputs rest on $color2 and step from there.
+const elevationTintOverlay: Record<Elevation, string> = {
+  none: "$color1",
+  small: "$color2",
+  medium: "$color3",
+  large: "$color4",
+};
+
+const elevationTintInput: Record<Elevation, string> = {
+  none: "$color2",
+  small: "$color3",
+  medium: "$color4",
+  large: "$color5",
+};
+
+// Axiom 14 light source: y-offset:blur = 0.5. Metrics match the maps
+// InputParts / getElevationWrapperProps already shipped.
+const elevationShadowMetrics: Record<
+  "$1" | "$2" | "$4",
+  { offsetY: number; radius: number; android: number }
+> = {
+  $1: { offsetY: 1, radius: 2, android: 2 },
+  $2: { offsetY: 3, radius: 6, android: 4 },
+  $4: { offsetY: 10, radius: 20, android: 8 },
+};
+
+const elevationKeyAlias: Record<string, "$1" | "$2" | "$4"> = {
+  $1: "$1",
+  $2: "$2",
+  $3: "$2",
+  $4: "$4",
+  $5: "$4",
+  "20": "$1",
+  "28": "$2",
+  "36": "$2",
+  "44": "$4",
+  "52": "$4",
+};
+
+const webShadowLight: Record<"$1" | "$2" | "$4", string> = {
+  $1: "0 1px 2px rgba(0,0,0,0.12), 0 0 1px rgba(0,0,0,0.08)",
+  $2: "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)",
+  $4: "0 10px 20px rgba(0,0,0,0.15), 0 3px 6px rgba(0,0,0,0.10)",
+};
+
+const webShadowDark: Record<"$1" | "$2" | "$4", string> = {
+  $1: "0 1px 2px rgba(255,255,255,0.08), 0 0 1px rgba(255,255,255,0.06)",
+  $2: "0 3px 6px rgba(255,255,255,0.10), 0 2px 4px rgba(255,255,255,0.06)",
+  $4: "0 10px 20px rgba(255,255,255,0.12), 0 3px 6px rgba(255,255,255,0.08)",
+};
+
+function elevationTokenKey(token: string | number | undefined): "$1" | "$2" | "$4" | undefined {
+  if (token == null) return undefined;
+  return elevationKeyAlias[String(token)];
+}
+
+function elevationPaint(
+  token: string | number | undefined,
+  scheme: ColorScheme,
+): ElevationPaintProps {
+  const key = elevationTokenKey(token);
+  if (!key) return {};
+  const metrics = elevationShadowMetrics[key];
+  const dark = scheme === "dark";
+  const paint: ElevationPaintProps = {
+    shadowColor: dark ? "$color12" : "#000",
+    shadowOffset: { width: 0, height: metrics.offsetY },
+    shadowOpacity: dark
+      ? key === "$4"
+        ? 0.12
+        : key === "$2"
+          ? 0.1
+          : 0.08
+      : key === "$1"
+        ? 0.12
+        : 0.15,
+    shadowRadius: metrics.radius,
+  };
+  if (isWeb) {
+    paint.style = { boxShadow: dark ? webShadowDark[key] : webShadowLight[key] };
+  }
+  return paint;
+}
+
+function elevationChromeFor(
+  token: string | number | undefined,
+  scheme: ColorScheme,
+): ElevationChromeProps {
+  const key = elevationTokenKey(token);
+  if (!key) return {};
+  return {
+    ...elevationPaint(token, scheme),
+    elevation: elevationShadowMetrics[key].android,
+  };
+}
+
 // Legibility floor: body/label text must never land below ~4.5:1 against its
 // surface. $color11 is the lowest ramp step that clears AA on color1/2
 // surfaces, so "low" clamps there ($color9 measured 1.29-3.43:1 — SB-R-01).
@@ -317,7 +436,10 @@ function resolveDisabled(disabledStyle: Knobs["disabledStyle"]): DisabledRecipe
 
 // ── State style resolver ──────────────────────────────────────
 
-function resolveStateKnobs(state: StateKnobs): {
+function resolveStateKnobs(
+  state: StateKnobs,
+  scheme: ColorScheme,
+): {
   control: ControlStateProps;
   text: TextStateProps;
   elevation: ElevationStateProps;
@@ -339,7 +461,12 @@ function resolveStateKnobs(state: StateKnobs): {
     control.padding = gapMap[state.space];
   }
   if (state.elevation !== undefined) {
-    elevation.elevation = elevationMap[state.elevation];
+    const token = elevationMap[state.elevation];
+    elevation.elevation = token;
+    Object.assign(elevation, elevationPaint(token, scheme));
+    if (scheme === "dark" && state.elevation !== "none") {
+      elevation.backgroundColor = elevationTintOverlay[state.elevation];
+    }
   }
   if (state.textAccent !== undefined) {
     text.color = textAccentColorMap[state.textAccent];
@@ -358,15 +485,19 @@ function resolveStateKnobs(state: StateKnobs): {
 
 // ── Resolver ──────────────────────────────────────────────────
 
-export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): ResolvedKnobs {
+export function resolveKnobs(
+  knobs: Knobs,
+  override?: KnobPropsOverride,
+  scheme: ColorScheme = "light",
+): ResolvedKnobs {
   const radiusToken = borderRadiusMap[knobs.borderRadius];
-  const outerRadiusToken = outerRadiusMap[knobs.borderRadius];
-  const borderWidthValue = borderWidthMap[knobs.borderWidth];
+  const nestedRadiusToken = nestedRadiusMap[knobs.borderRadius];
   const sizeToken = sizeTokenMap[knobs.size];
   const nestedPx = nestedControlPxMap[knobs.size];
   const nestedHitSlop = pressTargetHitSlop(nestedPx);
   const sizeRecipe = sizeRecipeForToken(sizeToken, {
     touch: isTouchable || isWebTouchable,
+    family: knobs.density === "compact" ? "controlCompact" : "control",
   });
   const paddingToken = panelPaddingMap[knobs.space];
   const gapToken = gapMap[knobs.space];
@@ -393,18 +524,38 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
   const containerSmoothing = knobs.borderRadius === "none" ? undefined : smoothing;
 
   const outlined = knobs.fillStyle === "outlined";
+  // LC-86 OUTLINED-HAIRLINE: outlined implies a minimum border. none on an
+  // outlined control still draws the enumerated `small` stop (0.5). Chromeless
+  // is filled + none. Components must not add a second local floor.
+  const borderWidthValue =
+    outlined && knobs.borderWidth === "none"
+      ? borderWidthMap.small
+      : borderWidthMap[knobs.borderWidth];
   const elevationToken = elevationMap[knobs.elevation];
+  const overlayElevationToken = overlayElevationMap[knobs.elevation];
+  const overlayPaintProps = elevationPaint(overlayElevationToken, scheme);
+  const elevationChrome = elevationChromeFor(elevationToken, scheme);
+  const dark = scheme === "dark";
+  // MPO-19 X5: `$background` (not `$color1`) so surface1/2/3 sub-themes move
+  // the fill. Dark + elevation still steps the filled rest fill up the ramp
+  // (LC-85).
+  const overlayFill =
+    dark && knobs.elevation !== "none" ? elevationTintOverlay[knobs.elevation] : "$background";
   const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
-  // One input surface (DF-19 / Axiom 5 ONE SOURCE): the knob resolves to the
-  // same tier forms' InputContainer uses (formInputColors.background.base =
-  // $color2), so Timeline's composer, RichEditor, and form fields agree on
-  // what an input surface is. $color6 forked a darker second voice.
-  const inputBackground = outlined ? "transparent" : "$color2";
-
-  const hover = resolveStateKnobs(knobs.hover);
-  const press = resolveStateKnobs(knobs.press);
-  const focus = resolveStateKnobs(knobs.focus);
-  const focusVisible = resolveStateKnobs(knobs.focusVisible);
+  // One input surface (DF-19 / Axiom 5 ONE SOURCE): Timeline's composer,
+  // RichEditor and form fields agree on what an input surface is.
+  // MPO-19 X6: `$background` not `$color2` so a surface sub-theme can move it.
+  // Dark + elevation steps the filled rest fill up the existing ramp (LC-85).
+  const inputBackground = outlined
+    ? "transparent"
+    : dark
+      ? elevationTintInput[knobs.elevation]
+      : "$background";
+
+  const hover = resolveStateKnobs(knobs.hover, scheme);
+  const press = resolveStateKnobs(knobs.press, scheme);
+  const focus = resolveStateKnobs(knobs.focus, scheme);
+  const focusVisible = resolveStateKnobs(knobs.focusVisible, scheme);
 
   const nonEmpty = <T extends object>(obj: T): T | undefined =>
     Object.keys(obj).length > 0 ? obj : undefined;
@@ -430,6 +581,8 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
     focusVisibleKnobProps: nonEmpty(focusVisible.elevation),
   };
 
+  const nestedRadius = { borderRadius: nestedRadiusToken, ...containerSmoothing };
+
   const knobProps: KnobProps = {
     borderRadius: {
       borderRadius: radiusToken,
@@ -437,33 +590,46 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
       borderWidth: borderWidthValue,
       ...scaleSmoothing,
     },
-    borderRadiusOuter: { borderRadius: outerRadiusToken, ...containerSmoothing },
+    borderRadiusNested: nestedRadius,
+    // MPO-19 X12: the old name for the same fragment, kept for one release so
+    // an out-of-tree consumer does not break on the rename. Same object, so
+    // the two cannot drift while both exist.
+    borderRadiusOuter: nestedRadius,
+    controlBorderFilled: { borderColor: "transparent", borderWidth: borderWidthValue },
+    controlBorderOutlined: {
+      borderColor: "$borderColor",
+      borderWidth: Math.max(borderWidthValue, 1),
+    },
     // Axiom 1 child-clip cap: padded containers (Card/Panel/DialogContent)
     // spread this after their radius-bearing fragment. Non-container parts
     // keep the uncapped `borderRadius` fragment.
     containerRadius: { borderRadius: containerRadiusValue, ...containerSmoothing },
     elevation: elevationToken,
+    overlayElevation: overlayElevationToken,
+    elevationChrome,
+    scheme,
     surface: {
-      backgroundColor: "$color1",
+      backgroundColor: "$background",
       borderColor: "$borderColor",
       borderWidth: borderWidthValue,
     },
     cardSurface: {
-      backgroundColor: "$color1",
+      backgroundColor: overlayFill,
       borderRadius: containerRadiusValue,
       padding: paddingToken,
       ...containerSmoothing,
     },
     elevatedSurface: {
-      backgroundColor: "$color1",
+      backgroundColor: overlayFill,
       borderColor: "$borderColor",
       borderWidth: borderWidthValue,
       borderRadius: radiusToken,
-      elevation: elevationToken,
+      elevation: overlayElevationToken,
+      ...overlayPaintProps,
       ...scaleSmoothing,
     },
     featureSurface: {
-      backgroundColor: "$color1",
+      backgroundColor: "$background",
       borderRadius: "$10",
       padding: "$6",
       // Bento marketing/auth card shadow: ~0px 9px 12px rgba(0,0,0,0.02) —

package/src/theme/sizeLadder.spec.ts

@@ -0,0 +1,84 @@
+/**
+ * MPO-46 / MPO-19 X1/X2 — the size ladder is the measured Tamagui v5 table
+ * (R6: real TABLE, no escape). padX / label / icon / radius at $2/$3/$4/$6
+ * come from tamagui-rendered-reference.md §6.1; Input padX is §6.2
+ * (one space half-step below the button). gap == radius at every size
+ * and every borderRadius knob stop.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  SIZE_RECIPE_RADII,
+  SIZE_RECIPE_RADIUS_STOPS,
+  TAMAGUI_CONTROL_SIZE_TABLE,
+  TAMAGUI_INPUT_PADX,
+  applyRadiusStop,
+  generateSizeRecipes,
+  recipeFamilies,
+  sizeRecipeForToken,
+  sizeRecipes,
+  type SizeRecipeRadiusStop,
+} from "./sizeRecipes";
+
+const MEASURED = {
+  $2: { paddingHorizontal: 7, fontSize: 12, iconSize: 12, radius: 5 },
+  $3: { paddingHorizontal: 13, fontSize: 13, iconSize: 14, radius: 7 },
+  $4: { paddingHorizontal: 18, fontSize: 14, iconSize: 16, radius: 9 },
+  $6: { paddingHorizontal: 32, fontSize: 18, iconSize: 20, radius: 16 },
+} as const;
+
+describe("MPO-46 size ladder — measured table, not a ratio (R6)", () => {
+  it("padX, label, icon and radius at $2/$3/$4/$6 match the Tamagui v5 reference", () => {
+    for (const token of ["$2", "$3", "$4", "$6"] as const) {
+      const recipe = sizeRecipeForToken(token);
+      const row = MEASURED[token];
+      expect(recipe.paddingHorizontal, `${token} padX`).toBe(row.paddingHorizontal);
+      expect(recipe.fontSize, `${token} label`).toBe(row.fontSize);
+      expect(recipe.iconSize, `${token} icon`).toBe(row.iconSize);
+      expect(SIZE_RECIPE_RADII[token], `${token} radius`).toBe(row.radius);
+      expect(TAMAGUI_CONTROL_SIZE_TABLE[token]).toEqual(row);
+    }
+  });
+
+  it("does not ship the linear-ratio $2 defects (padX 11, label 9, flat radius 9)", () => {
+    const two = sizeRecipeForToken("$2");
+    expect(two.paddingHorizontal).not.toBe(11);
+    expect(two.fontSize).not.toBe(9);
+    expect(SIZE_RECIPE_RADII.$2).not.toBe(9);
+    expect(SIZE_RECIPE_RADII.$2).not.toBe(SIZE_RECIPE_RADII.$6);
+  });
+
+  it("Button / Select trigger / ListItem $4 is 44 / padX 18 / radius 9; Input padX is 16", () => {
+    const button = sizeRecipes.$4;
+    expect(button.height).toBe(44);
+    expect(button.paddingHorizontal).toBe(18);
+    expect(SIZE_RECIPE_RADII.$4).toBe(9);
+    expect(TAMAGUI_INPUT_PADX.$4).toBe(16);
+    expect(recipeFamilies.controlCompact.recipes.$4.paddingHorizontal).toBe(16);
+    expect(recipeFamilies.controlCompact.recipes.$4.height).toBe(44);
+    expect(recipeFamilies.controlCompact.radii.$4).toBe(9);
+  });
+});
+
+describe("MPO-46 gap == radius", () => {
+  it("holds at every size step", () => {
+    const generated = generateSizeRecipes();
+    for (const token of Object.keys(generated.recipes)) {
+      expect(generated.recipes[token].gap, `control ${token}`).toBe(generated.radii[token]);
+      expect(generated.families.controlCompact.recipes[token].gap, `compact ${token}`).toBe(
+        generated.families.controlCompact.radii[token],
+      );
+    }
+  });
+
+  it("holds at every borderRadius knob stop", () => {
+    const stops = Object.keys(SIZE_RECIPE_RADIUS_STOPS) as SizeRecipeRadiusStop[];
+    for (const token of ["$2", "$3", "$4", "$5", "$6"] as const) {
+      const recipe = sizeRecipeForToken(token);
+      for (const stop of stops) {
+        const next = applyRadiusStop(recipe, stop);
+        expect(next.gap, `${token} @ ${stop}`).toBe(SIZE_RECIPE_RADIUS_STOPS[stop]);
+      }
+    }
+  });
+});