@multiplatform.one/theme 7.34.3 → 7.35.0

package/src/theme/resolveKnobs.spec.ts

@@ -4,9 +4,6 @@ import {
   defaultKnobs,
   emptyStateKnobs,
   FillStyle,
-  Space,
-  Size,
-  Density,
   CornerSmoothing,
   FieldLabelPlacement,
   RequiredMarking,
@@ -22,12 +19,21 @@ import type { KnobProps } from "./recipes";
 import { cornerSmoothClassName } from "./cornerSmoothing";
 import { defaultPreset, boldPreset, heroPreset } from "./presets";
 import {
-  applyDensity,
   capContainerRadius,
+  capFieldRadius,
   containerCapProps,
+  labelFontSizeFor,
+  nestedControlPx,
+  paintedCardFill,
+  panelPaddingPx,
   resolveKnobs,
   resolvePageTitleScale,
+  spacingRoles,
+  sizedElevation,
 } from "./resolveKnobs";
+import { getActiveScaleTokens, setActiveScaleTokens } from "./scale/activeScale";
+import { generateScale } from "./scale/generateScale";
+import { defaultScaleInputs } from "./scale/scaleInputs";
 import {
   normalizeToHex,
   relativeLuminance,
@@ -40,14 +46,29 @@ function knobsWith(overrides: Partial<Knobs>): Knobs {
   return { ...defaultKnobs, ...overrides };
 }
 
+/** Resolve with another scale installed, then put the default scale back. */
+function onScale<T>(control: number, type: number, read: () => T): T {
+  const previous = getActiveScaleTokens();
+  setActiveScaleTokens(generateScale({ control, type }).tokens);
+  try {
+    return read();
+  } finally {
+    setActiveScaleTokens(previous);
+  }
+}
+
+const defaultScaleTokens = generateScale(defaultScaleInputs).tokens;
+
 const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "borderRadius",
   "borderRadiusNested",
   "borderRadiusOuter",
   "containerRadius",
+  "fieldRadius",
   "elevation",
   "overlayElevation",
   "elevationChrome",
+  "thumbShadow",
   "scheme",
   "surface",
   "cardSurface",
@@ -55,6 +76,7 @@ const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "featureSurface",
   "inputSurface",
   "panelPadding",
+  "gapSm",
   "gap",
   "gapLg",
   "sizeToken",
@@ -63,9 +85,16 @@ const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "control",
   "controlType",
   "controlIcon",
+  "menuRow",
+  "menuRowType",
+  "tab",
+  "tabType",
+  "tabHitSlop",
+  "bar",
   "heading",
   "pageTitle",
   "body",
+  "typography",
   "textWeight",
   "transition",
   "outlined",
@@ -73,9 +102,6 @@ const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "textAccent",
   "textAccentColor",
   "inputBackground",
-  "space",
-  "size",
-  "density",
   "fieldLabelPlacement",
   "requiredMarking",
   "tableZebra",
@@ -160,14 +186,49 @@ describe("resolveKnobs", () => {
     expect(a).toEqual(b);
   });
 
+  it("menuRow, tab and bar fragments read the recipe families and the scale", () => {
+    const desktop = resolveKnobs(defaultKnobs, undefined, "light", { touch: false }).knobProps;
+    expect(desktop.menuRow).toEqual({ minHeight: 36, paddingHorizontal: 12, gap: 8 });
+    expect(desktop.menuRowType).toEqual({ fontSize: 15 });
+    expect(desktop.tab.height).toBe(36);
+    expect(desktop.tabType).toEqual({ fontSize: 15 });
+    expect(desktop.tabHitSlop).toEqual({ top: 4, bottom: 4, left: 4, right: 4 });
+    expect(desktop.bar).toEqual({
+      frame: { paddingVertical: "$2", paddingHorizontal: "$4", minHeight: 52 },
+      sizeToken: "$3",
+    });
+    const touch = resolveKnobs(defaultKnobs, undefined, "light", { touch: true }).knobProps;
+    expect(touch.menuRow.minHeight).toBe(44);
+    expect(touch.tab.height).toBe(44);
+    expect(touch.tabHitSlop).toEqual({ top: 0, bottom: 0, left: 0, right: 0 });
+  });
+
   it("matches snapshot for defaultKnobs", () => {
     const resolved = resolveKnobs(defaultKnobs);
     expect(resolved).toMatchSnapshot();
   });
 
-  // ── T1.1g — expectedKnobPropKeys includes "size" ────────
-  it('expectedKnobPropKeys includes "size"', () => {
-    expect(expectedKnobPropKeys).toContain("size");
+  it("knobProps carries no size, space or density channel (LC-100)", () => {
+    const { knobProps } = resolveKnobs(defaultKnobs);
+    for (const retired of ["size", "space", "density"]) {
+      expect(expectedKnobPropKeys).not.toContain(retired);
+      expect(knobProps).not.toHaveProperty(retired);
+    }
+  });
+
+  it("Knobs has no size, space or density member (LC-100)", () => {
+    // @ts-expect-error size is not a knob: a use site passes Tamagui's own size token
+    const size: Knobs["size"] = undefined;
+    // @ts-expect-error space is not a knob: spacing is the scale's token values
+    const space: Knobs["space"] = undefined;
+    // @ts-expect-error density is not a knob: a preset carries its own scale
+    const density: Knobs["density"] = undefined;
+    expect([size, space, density]).toEqual([undefined, undefined, undefined]);
+    for (const retired of ["size", "space", "density"]) {
+      expect(defaultKnobs).not.toHaveProperty(retired);
+      expect(defaultPreset.knobs).not.toHaveProperty(retired);
+      expect(boldPreset.knobs).not.toHaveProperty(retired);
+    }
   });
 
   // ── borderRadius ──────────────────────────────────────────
@@ -220,75 +281,83 @@ describe("resolveKnobs", () => {
 
   // ── elevation ──────────────────────────────────────────────
 
-  describe("elevation knob", () => {
-    it('maps "none" → undefined', () => {
-      expect(resolveKnobs(knobsWith({ elevation: "none" })).knobProps.elevation).toBeUndefined();
-    });
-
-    it('maps "small" → undefined: controls paint no resting shadow at the default (MPO-96)', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ elevation: "small" }));
-      expect(knobProps.elevation).toBeUndefined();
-      expect(knobProps.elevationChrome).toEqual({});
-    });
-
-    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");
-    });
-
-    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.12);
-      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({});
+  describe("sizedElevation", () => {
+    it.each([
+      [26, 8, 15, 16],
+      [28, 8, 16, 16],
+      [36, 10, 20, 20],
+      [44, 12, 24, 24],
+      [52, 14, 28, 28],
+    ])("%i px uses the Tamagui formula", (px, offsetY, radius, android) => {
+      expect(sizedElevation(px)).toEqual({ offsetY, radius, android });
     });
+  });
 
-    it("dark outlined inputs stay transparent — tint is for filled surfaces", () => {
-      const { knobProps } = resolveKnobs(
-        knobsWith({ elevation: "large", fillStyle: "outlined" }),
-        undefined,
-        "dark",
+  describe("elevation knob", () => {
+    for (const scheme of ["light", "dark"] as const) {
+      for (const [stop, key] of [
+        ["none", undefined],
+        ["small", undefined],
+        ["medium", "$2"],
+        ["large", "$4"],
+      ] as const) {
+        it(`${scheme} ${stop} paints the active size formula`, () => {
+          const { knobProps } = resolveKnobs(knobsWith({ elevation: stop }), undefined, scheme);
+          expect(knobProps.elevation).toBe(key);
+          expect(knobProps.cardSurface.backgroundColor).toBe("$background");
+          expect(knobProps.elevatedSurface.backgroundColor).toBe(
+            scheme === "dark" ? "$color4" : "$background",
+          );
+          expect(knobProps.elevatedSurface.borderColor).toBe(
+            scheme === "dark" ? "$color6" : "$borderColor",
+          );
+          if (!key) {
+            expect(knobProps.elevationChrome).toEqual({});
+            return;
+          }
+          const { offsetY, radius, android } = sizedElevation(getActiveScaleTokens().size[key]);
+          expect(knobProps.elevationChrome).toEqual({
+            shadowColor: "$shadowColor",
+            shadowOffset: { width: 0, height: offsetY },
+            shadowRadius: radius,
+            shadowOpacity: 1,
+            elevation: android,
+            style: { boxShadow: `0px ${offsetY}px ${radius}px var(--shadowColor)` },
+          });
+          expect(knobProps.elevationChrome.shadowColor).not.toBe("$color12");
+        });
+      }
+    }
+    it("dark elevated fill is one palette step above the Card surface", async () => {
+      const { createDefaultThemeConfig } = await import("./createDefaultThemeConfig");
+      const themes = createDefaultThemeConfig().tamagui.themes;
+      const { knobProps } = resolveKnobs(defaultKnobs, undefined, "dark");
+      const palette = Array.from(
+        { length: 12 },
+        (_, index) => themes.dark[`color${index + 1}`].val,
       );
-      expect(knobProps.inputBackground).toBe("transparent");
       expect(knobProps.elevatedSurface.backgroundColor).toBe("$color4");
+      const cardIndex = palette.indexOf(themes.dark_Card.background.val);
+      const overlayIndex = palette.indexOf(themes.dark.color4.val);
+      expect(cardIndex).toBeGreaterThanOrEqual(0);
+      expect(overlayIndex - cardIndex).toBe(1);
+    });
+
+    it("recomputes paint when the active scale changes", () => {
+      const before = resolveKnobs(knobsWith({ elevation: "large" })).knobProps;
+      onScale(48, 16, () => {
+        const after = resolveKnobs(knobsWith({ elevation: "large" })).knobProps;
+        const { offsetY, radius } = sizedElevation(getActiveScaleTokens().size.$4);
+        expect(after.elevationChrome.style?.boxShadow).toBe(
+          `0px ${offsetY}px ${radius}px var(--shadowColor)`,
+        );
+        expect(after.elevationChrome).not.toEqual(before.elevationChrome);
+      });
     });
   });
 
-  // ── elevation on NATIVE (SB-N-04) ──────────────────────────
-  // Android's RCTView `elevation` prop is a Double; a token string reaching a
-  // plain RN View kills the ReactHost. Native must emit the numeric
-  // tokens.size values Tamagui would resolve those tokens to.
-
   describe("elevation knob (native)", () => {
-    it("emits RN-safe numbers, never token strings", async () => {
+    it("returns active scale numbers with the same paint in both schemes", async () => {
       vi.resetModules();
       vi.doMock("@multiplatform.one/platform", () => ({
         isWeb: false,
@@ -296,23 +365,57 @@ describe("resolveKnobs", () => {
         isWebTouchable: false,
       }));
       const { resolveKnobs: resolveNative } = await import("./resolveKnobs");
+      const active = await import("./scale/activeScale");
+      const previous = active.getActiveScaleTokens();
       try {
-        expect(resolveNative(knobsWith({ elevation: "none" })).knobProps.elevation).toBeUndefined();
-        const small = resolveNative(
-          knobsWith({ elevation: "small", hover: { elevation: "medium" } }),
-        );
-        expect(small.knobProps.elevation).toBeUndefined();
-        expect(small.knobProps.elevationChrome).toEqual({});
-        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);
+        for (const control of [40, 48]) {
+          active.setActiveScaleTokens(generateScale({ control }).tokens);
+          for (const scheme of ["light", "dark"] as const) {
+            for (const [stop, key, overlay] of [
+              ["none", undefined, undefined],
+              ["small", undefined, "$4"],
+              ["medium", "$2", "$4.5"],
+              ["large", "$4", "$5"],
+            ] as const) {
+              const { knobProps } = resolveNative(
+                knobsWith({ elevation: stop }),
+                undefined,
+                scheme,
+              );
+              expect(knobProps.elevation).toBe(
+                key ? active.getActiveScaleTokens().size[key] : undefined,
+              );
+              expect(knobProps.overlayElevation).toBe(
+                overlay ? active.getActiveScaleTokens().size[overlay] : undefined,
+              );
+              expect(knobProps.elevatedSurface.elevation).toBe(knobProps.overlayElevation);
+              const state = resolveNative(
+                knobsWith({ hover: { elevation: stop } }),
+                undefined,
+                scheme,
+              );
+              expect(state.elevation.hoverKnobProps?.elevation).toBe(
+                key ? active.getActiveScaleTokens().size[key] : undefined,
+              );
+
+              expect(knobProps.elevationChrome.style).toBeUndefined();
+              if (key) {
+                const metrics = sizedElevation(active.getActiveScaleTokens().size[key]);
+                expect(knobProps.elevationChrome).toEqual({
+                  shadowColor: "$shadowColor",
+                  shadowOpacity: 1,
+                  shadowOffset: { width: 0, height: metrics.offsetY },
+                  shadowRadius: metrics.radius,
+                  elevation: metrics.android,
+                });
+              } else expect(knobProps.elevationChrome).toEqual({});
+              expect(knobProps.thumbShadow.style).toBeUndefined();
+              expect(knobProps.thumbShadow.shadowColor).toBe("$shadowColor");
+            }
+          }
+        }
       } finally {
+        active.setActiveScaleTokens(previous);
         vi.doUnmock("@multiplatform.one/platform");
         vi.resetModules();
       }
@@ -320,48 +423,54 @@ describe("resolveKnobs", () => {
   });
 
   describe("overlay elevation ladder (MPO-99)", () => {
-    const paint = (elevation: "small" | "medium" | "large", scheme: "light" | "dark") =>
-      resolveKnobs(knobsWith({ elevation }), undefined, scheme).knobProps;
-
-    it("overlay medium and large paint the reference popper and dialog shadows", () => {
-      expect(paint("medium", "light").overlayElevation).toBe("$3");
-      expect(paint("medium", "light").elevatedSurface.style?.boxShadow).toBe(
-        "0 4px 8px rgba(0,0,0,0.10), 0 12px 32px rgba(0,0,0,0.08)",
-      );
-      expect(paint("large", "light").overlayElevation).toBe("$5");
-      expect(paint("large", "light").elevatedSurface.style?.boxShadow).toBe(
-        "0 12px 24px rgba(0,0,0,0.12)",
-      );
-    });
-
-    it("overlay medium and large differ from control medium and large, in both schemes", () => {
-      for (const scheme of ["light", "dark"] as const) {
-        for (const stop of ["medium", "large"] as const) {
-          const knobProps = paint(stop, scheme);
-          expect(knobProps.elevatedSurface.style?.boxShadow).toBeTruthy();
-          expect(knobProps.elevationChrome.style?.boxShadow).toBeTruthy();
+    for (const scheme of ["light", "dark"] as const) {
+      for (const [stop, key] of [
+        ["small", "$4"],
+        ["medium", "$4.5"],
+        ["large", "$5"],
+      ] as const) {
+        it(`${scheme} ${stop} uses its own overlay stop`, () => {
+          const { knobProps } = resolveKnobs(knobsWith({ elevation: stop }), undefined, scheme);
+          const { offsetY, radius } = sizedElevation(getActiveScaleTokens().size[key]);
+          expect(knobProps.overlayElevation).toBe(key);
+          expect(knobProps.elevatedSurface.shadowColor).toBe("$shadowColor");
+          expect(knobProps.elevatedSurface.shadowColor).not.toBe("$color12");
+          expect(knobProps.elevatedSurface.shadowOpacity).toBe(1);
+          expect(knobProps.elevatedSurface.style?.boxShadow).toBe(
+            `0px ${offsetY}px ${radius}px var(--shadowColor)`,
+          );
           expect(knobProps.elevatedSurface.style?.boxShadow).not.toBe(
             knobProps.elevationChrome.style?.boxShadow,
           );
-        }
+        });
       }
+    }
+    it("none has no overlay paint", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ elevation: "none" }));
+      expect(knobProps.overlayElevation).toBeUndefined();
+      expect(knobProps.elevatedSurface.style).toBeUndefined();
+      expect(knobProps.elevatedSurface.shadowColor).toBeUndefined();
     });
+  });
 
-    it("dark keeps each overlay stop's geometry and inverts the hue (LC-85)", () => {
-      expect(paint("medium", "dark").elevatedSurface.style?.boxShadow).toBe(
-        "0 4px 8px rgba(255,255,255,0.10), 0 12px 32px rgba(255,255,255,0.08)",
-      );
-      expect(paint("large", "dark").elevatedSurface.style?.boxShadow).toBe(
-        "0 12px 24px rgba(255,255,255,0.12)",
-      );
-    });
-
-    it("overlays keep a shadow at the default stop while controls go flat (MPO-96)", () => {
-      const knobProps = paint("small", "light");
-      expect(knobProps.elevationChrome).toEqual({});
-      expect(knobProps.elevatedSurface.style?.boxShadow).toBe(
-        "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)",
-      );
+  describe("thumbShadow", () => {
+    it("paints the half-size stop at every elevation stop and follows the active scale", () => {
+      for (const control of [40, 48])
+        onScale(control, 16, () => {
+          for (const elevation of ["none", "small", "medium", "large"] as const) {
+            const { offsetY, radius, android } = sizedElevation(
+              getActiveScaleTokens().size["$0.5"],
+            );
+            expect(resolveKnobs(knobsWith({ elevation })).knobProps.thumbShadow).toEqual({
+              shadowColor: "$shadowColor",
+              shadowOffset: { width: 0, height: offsetY },
+              shadowOpacity: 1,
+              shadowRadius: radius,
+              elevation: android,
+              style: { boxShadow: `0px ${offsetY}px ${radius}px var(--shadowColor)` },
+            });
+          }
+        });
     });
   });
 
@@ -411,113 +520,143 @@ describe("resolveKnobs", () => {
     });
   });
 
-  // ── space ──────────────────────────────────────────────
+  // ── spacing roles (SP-GAP, A9) ─────────────────────────────
 
-  describe("space knob", () => {
-    it('maps panelPadding "small" → "$3"', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "small" }));
-      expect(knobProps.panelPadding.padding).toBe("$3");
-    });
-
-    it('maps gap "large" → "$5"', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "large" }));
-      expect(knobProps.gap.gap).toBe("$5");
-    });
-
-    it("passes space value through to knobProps", () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "large" }));
-      expect(knobProps.space).toBe("large");
-    });
-
-    // T2.1a — space "large" no longer changes sizeToken
-    it("space does not affect sizeToken", () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "large", size: "medium" }));
-      expect(knobProps.sizeToken).toBe("$4");
-    });
-
-    // T2.1b — space "small" still maps panelPadding regardless of size
-    it('space "small" maps panelPadding → "$3" regardless of size', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "small", size: "large" }));
-      expect(knobProps.panelPadding.padding).toBe("$3");
-    });
-
-    // T2.1c — space "large" still maps gapLg → "$6" regardless of size
-    it('space "large" maps gapLg → "$6" regardless of size', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ space: "large", size: "small" }));
-      expect(knobProps.gapLg.gap).toBe("$6");
-    });
-  });
-
-  // ── size ──────────────────────────────────────────────────
-
-  describe("size knob", () => {
-    // T1.1b — size "large" maps sizeToken → "$5"
-    it('maps sizeToken "large" → "$5"', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ size: "large" }));
-      expect(knobProps.sizeToken).toBe("$5");
-    });
-
-    // T1.1c — size "small" maps sizeToken → "$3"
-    it('maps sizeToken "small" → "$3"', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ size: "small" }));
-      expect(knobProps.sizeToken).toBe("$3");
-    });
-
-    // T1.1e — knobProps.size passthrough
-    it("passes size value through to knobProps", () => {
-      for (const val of Object.values(Size)) {
-        const { knobProps } = resolveKnobs(knobsWith({ size: val }));
-        expect(knobProps.size).toBe(val);
+  describe("spacing roles (SP-GAP)", () => {
+    it("defaults: gapSm $2, gap $3, gapLg $5, panelPadding $4, sizeToken $true", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.gapSm).toEqual({ gap: "$2" });
+      expect(knobProps.gap).toEqual({ gap: "$3" });
+      expect(knobProps.gapLg).toEqual({ gap: "$5" });
+      expect(knobProps.panelPadding).toEqual({ padding: "$4" });
+      expect(knobProps.sizeToken).toBe("$true");
+    });
+
+    it("the roles are the same keys under every knob value: no knob moves them", () => {
+      const variants: Partial<Knobs>[] = [
+        { borderRadius: "full" },
+        { borderRadius: "none" },
+        { fillStyle: "outlined" },
+        { elevation: "large" },
+        { fontWeight: "bold" },
+        { textAccent: "low" },
+        { hover: { borderWidth: "large" } },
+      ];
+      for (const variant of variants) {
+        const { knobProps } = resolveKnobs(knobsWith(variant));
+        expect(knobProps.gapSm.gap, JSON.stringify(variant)).toBe(spacingRoles.gapSm);
+        expect(knobProps.gap.gap, JSON.stringify(variant)).toBe(spacingRoles.gap);
+        expect(knobProps.gapLg.gap, JSON.stringify(variant)).toBe(spacingRoles.gapLg);
+        expect(knobProps.panelPadding.padding, JSON.stringify(variant)).toBe(
+          spacingRoles.panelPadding,
+        );
       }
     });
 
-    // T1.1f — independent axes: size "large" + space "small"
-    it('size "large" + space "small" → sizeToken "$5" AND gap "$2"', () => {
-      const { knobProps } = resolveKnobs(knobsWith({ size: "large", space: "small" }));
-      expect(knobProps.sizeToken).toBe("$5");
-      expect(knobProps.gap.gap).toBe("$2");
-    });
-
-    // T2.1e — changing size does NOT affect panelPadding, gap, or gapLg
-    it("changing size does not affect panelPadding, gap, or gapLg", () => {
-      const baseline = resolveKnobs(knobsWith({ size: "medium", space: "medium" }));
-      for (const sizeVal of Object.values(Size)) {
-        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal, space: "medium" }));
-        expect(knobProps.panelPadding).toEqual(baseline.knobProps.panelPadding);
-        expect(knobProps.gap).toEqual(baseline.knobProps.gap);
-        expect(knobProps.gapLg).toEqual(baseline.knobProps.gapLg);
+    it("tight < within-group < inset < between-groups on the default scale (6 / 12 / 16 / 21)", () => {
+      const px = (key: string) => defaultScaleTokens.space[key as "$2"];
+      expect(px(spacingRoles.gapSm)).toBe(6);
+      expect(px(spacingRoles.gap)).toBe(12);
+      expect(px(spacingRoles.panelPadding)).toBe(16);
+      expect(px(spacingRoles.gapLg)).toBe(21);
+    });
+
+    it("a preset scale changes the roles' px, never their keys", () => {
+      for (const [control, type] of [
+        [36, 14],
+        [48, 16],
+      ] as const) {
+        const { knobProps, padding } = onScale(control, type, () => ({
+          knobProps: resolveKnobs(defaultKnobs).knobProps,
+          padding: panelPaddingPx(),
+        }));
+        const scale = generateScale({ control, type }).tokens;
+        expect(knobProps.gap).toEqual({ gap: "$3" });
+        expect(knobProps.panelPadding).toEqual({ padding: "$4" });
+        expect(padding, `${control}/${type}`).toBe(scale.space.$4);
+        expect(padding, `${control}/${type}`).not.toBe(defaultScaleTokens.space.$4);
       }
     });
 
-    // T2.1f — default knobs produce identical output to prior default
-    it("default knobs (size+space both medium) produce consistent output", () => {
-      const resolved = resolveKnobs(defaultKnobs);
-      expect(resolved.knobProps.sizeToken).toBe("$4");
-      expect(resolved.knobProps.gap.gap).toBe("$4");
-      expect(resolved.knobProps.panelPadding.padding).toBe("$4");
-      expect(resolved.knobProps.gapLg.gap).toBe("$5");
+    it("state knobs carry no padding: space is not a state channel", () => {
+      const { control } = resolveKnobs(knobsWith({ hover: { borderWidth: "large" } }));
+      expect(control.hoverKnobProps).not.toHaveProperty("padding");
     });
+  });
 
-    it("fills control / controlType / controlIcon from the size recipe", () => {
+  // ── size token (environment.sizeToken) ────────────────────
+
+  describe("size token", () => {
+    it("fills control / controlType / controlIcon from the $true recipe by default", () => {
       const { knobProps } = resolveKnobs(defaultKnobs);
       expect(knobProps.control).toEqual({
-        height: 44,
-        paddingHorizontal: 18,
-        gap: 9,
+        height: 40,
+        paddingHorizontal: 16,
+        gap: 8,
       });
-      expect(knobProps.controlType).toEqual({ fontSize: 14 });
+      expect(knobProps.controlType).toEqual({ fontSize: 15 });
       expect(knobProps.controlIcon).toEqual({ width: 16, height: 16 });
       expect(knobProps.control).not.toHaveProperty("borderRadius");
       expect(knobProps.controlType).not.toHaveProperty("borderRadius");
       expect(knobProps.controlIcon).not.toHaveProperty("borderRadius");
     });
 
-    it("small and large share the same borderRadius fragment", () => {
-      const small = resolveKnobs(knobsWith({ size: "small" }));
-      const large = resolveKnobs(knobsWith({ size: "large" }));
-      expect(small.knobProps.control.height).toBe(36);
-      expect(large.knobProps.control.height).toBe(52);
-      expect(small.knobProps.borderRadius).toEqual(large.knobProps.borderRadius);
+    it("environment.sizeToken picks the recipe at that $size key", () => {
+      const small = resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "$3" });
+      const large = resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "$5" });
+      expect(small.knobProps.sizeToken).toBe("$3");
+      expect(small.knobProps.control.height).toBe(defaultScaleTokens.size.$3);
+      expect(large.knobProps.sizeToken).toBe("$5");
+      expect(large.knobProps.control.height).toBe(defaultScaleTokens.size.$5);
+    });
+
+    it("a size token is not a $size key falls back to $true", () => {
+      expect(
+        resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "40" }).knobProps.sizeToken,
+      ).toBe("$true");
+      expect(
+        resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "$medium" }).knobProps.control
+          .height,
+      ).toBe(40);
+    });
+
+    it("the size token never moves the spacing roles or the radius fragment", () => {
+      const baseline = resolveKnobs(defaultKnobs).knobProps;
+      for (const sizeToken of ["$2", "$3", "$4", "$5", "$6"]) {
+        const { knobProps } = resolveKnobs(defaultKnobs, undefined, "light", { sizeToken });
+        expect(knobProps.gapSm, sizeToken).toEqual(baseline.gapSm);
+        expect(knobProps.gap, sizeToken).toEqual(baseline.gap);
+        expect(knobProps.gapLg, sizeToken).toEqual(baseline.gapLg);
+        expect(knobProps.panelPadding, sizeToken).toEqual(baseline.panelPadding);
+        expect(knobProps.borderRadius, sizeToken).toEqual(baseline.borderRadius);
+      }
+    });
+
+    it("label type is the body key at the size key, rounding half steps up", () => {
+      expect(labelFontSizeFor("$true")).toBe("$true");
+      expect(labelFontSizeFor("$4")).toBe("$4");
+      expect(labelFontSizeFor("$3")).toBe("$3");
+      expect(labelFontSizeFor("$3.5")).toBe("$4");
+      expect(labelFontSizeFor("$5")).toBe("$5");
+      expect(labelFontSizeFor("$1")).toBe("$1");
+      const { knobProps } = resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "$3" });
+      expect(knobProps.label.fontSize).toBe("$3");
+      expect(resolveKnobs(defaultKnobs).knobProps.label.fontSize).toBe(
+        resolveKnobs(defaultKnobs).knobProps.sizeToken,
+      );
+    });
+
+    it("nestedControl is 32/44 of the size token's $size, below the floor, press restored by hitSlop", () => {
+      const medium = resolveKnobs(defaultKnobs).knobProps.nestedControl;
+      expect(medium.px).toBe(nestedControlPx("$true"));
+      expect(medium.width).toBe(nestedControlPx("$true"));
+      expect(medium.maxWidth).toBe(medium.px);
+      expect(medium.hitSlop).toEqual({ top: 8, bottom: 8, left: 8, right: 8 });
+      const small = resolveKnobs(defaultKnobs, undefined, "light", { sizeToken: "$3" }).knobProps
+        .nestedControl;
+      expect(small.px).toBe(Math.round((defaultScaleTokens.size.$3 * 32) / 44));
+      expect(nestedControlPx("$5")).toBe(Math.round((defaultScaleTokens.size.$5 * 32) / 44));
+      expect(onScale(36, 14, () => nestedControlPx("$true"))).toBe(Math.round((36 * 32) / 44));
     });
   });
 
@@ -528,21 +667,21 @@ describe("resolveKnobs", () => {
       const { knobProps } = resolveKnobs(defaultKnobs);
       expect(knobProps.cardSurface).toEqual({
         backgroundColor: "$background",
-        borderRadius: "$4",
+        borderRadius: "$6",
         padding: "$4",
       });
       expect(knobProps.cardSurface).not.toHaveProperty("borderWidth");
       expect(knobProps.cardSurface).not.toHaveProperty("elevation");
     });
 
-    it("cardSurface tracks borderRadius and space knobs (cap bites: large radius 16px > small padding 13px)", () => {
-      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "large", space: "small" }));
-      expect(knobProps.cardSurface.borderRadius).toBe(13);
-      expect(knobProps.cardSurface.padding).toBe("$3");
+    it("cardSurface tracks the borderRadius knob (cap bites at full: 44px > the 16px panelPadding)", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "full" }));
+      expect(knobProps.cardSurface.borderRadius).toBe(16);
+      expect(knobProps.cardSurface.padding).toBe("$4");
     });
 
     it("cardSurface keeps the radius token while it fits the padding", () => {
-      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "large", space: "medium" }));
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "medium" }));
       expect(knobProps.cardSurface.borderRadius).toBe("$6");
     });
 
@@ -578,23 +717,16 @@ describe("resolveKnobs", () => {
       expect(knobProps.featureSurface).not.toHaveProperty("borderWidth");
     });
 
-    it("featureSurface keeps $10 / $6 at the default knobs and every other stop moves them (MPO-21 GL-59)", () => {
+    it("featureSurface keeps $10 / $6 at the default knobs and every other radius stop moves the radius (MPO-21 GL-59)", () => {
       expect(defaultKnobs.borderRadius).toBe("medium");
-      expect(defaultKnobs.space).toBe("medium");
       for (const borderRadius of ["none", "small", "large", "full"] as const) {
-        expect(
-          resolveKnobs(knobsWith({ borderRadius })).knobProps.featureSurface.borderRadius,
-          borderRadius,
-        ).not.toBe("$10");
-      }
-      for (const space of ["small", "large"] as const) {
-        expect(resolveKnobs(knobsWith({ space })).knobProps.featureSurface.padding, space).not.toBe(
-          "$6",
-        );
+        const { featureSurface } = resolveKnobs(knobsWith({ borderRadius })).knobProps;
+        expect(featureSurface.borderRadius, borderRadius).not.toBe("$10");
+        expect(featureSurface.padding, borderRadius).toBe(spacingRoles.featurePadding);
       }
     });
 
-    it("featureSurface radius follows the radius knob, one token per stop around $10, uncapped by space", () => {
+    it("featureSurface radius follows the radius knob, one token per stop around $10", () => {
       const expected = {
         none: "$0",
         small: "$9",
@@ -603,46 +735,20 @@ describe("resolveKnobs", () => {
         full: "$12",
       } as const;
       for (const [borderRadius, token] of Object.entries(expected)) {
-        for (const space of ["small", "medium", "large"] as const) {
-          expect(
-            resolveKnobs(knobsWith({ borderRadius: borderRadius as Knobs["borderRadius"], space }))
-              .knobProps.featureSurface.borderRadius,
-            `${borderRadius}/${space}`,
-          ).toBe(token);
-        }
-      }
-    });
-
-    it("featureSurface padding follows the space knob, one token per stop around $6", () => {
-      const expected = { small: "$5", medium: "$6", large: "$7" } as const;
-      for (const [space, token] of Object.entries(expected)) {
-        for (const borderRadius of ["none", "small", "medium", "large", "full"] as const) {
-          expect(
-            resolveKnobs(knobsWith({ borderRadius, space: space as Knobs["space"] })).knobProps
-              .featureSurface.padding,
-            `${borderRadius}/${space}`,
-          ).toBe(token);
-        }
+        expect(
+          resolveKnobs(knobsWith({ borderRadius: borderRadius as Knobs["borderRadius"] })).knobProps
+            .featureSurface.borderRadius,
+          borderRadius,
+        ).toBe(token);
       }
     });
 
-    it("compact density steps featureSurface padding through the space knob", () => {
-      const { knobProps } = resolveKnobs(applyDensity(knobsWith({ density: "compact" })));
-      expect(knobProps.featureSurface.padding).toBe("$5");
-      expect(knobProps.featureSurface.borderRadius).toBe("$10");
-    });
-
-    it("featureSurface never clips a child at its inset: padding >= radius x (1 - 1/sqrt 2) at every stop pair", () => {
+    it("featureSurface never clips a child at its inset: padding >= radius x (1 - 1/sqrt 2) at every radius stop", () => {
       for (const borderRadius of ["none", "small", "medium", "large", "full"] as const) {
-        for (const space of ["small", "medium", "large"] as const) {
-          const { featureSurface } = resolveKnobs(knobsWith({ borderRadius, space })).knobProps;
-          const radiusPx = (tokens.radius as any)[featureSurface.borderRadius.slice(1)]
-            .val as number;
-          const paddingPx = (tokens.space as any)[featureSurface.padding.slice(1)].val as number;
-          expect(paddingPx, `${borderRadius}/${space}`).toBeGreaterThanOrEqual(
-            radiusPx * (1 - Math.SQRT1_2),
-          );
-        }
+        const { featureSurface } = resolveKnobs(knobsWith({ borderRadius })).knobProps;
+        const radiusPx = (tokens.radius as any)[featureSurface.borderRadius.slice(1)].val as number;
+        const paddingPx = (tokens.space as any)[featureSurface.padding.slice(1)].val as number;
+        expect(paddingPx, borderRadius).toBeGreaterThanOrEqual(radiusPx * (1 - Math.SQRT1_2));
       }
     });
   });
@@ -650,78 +756,89 @@ describe("resolveKnobs", () => {
   // ── container radius cap (Axiom 1 CLIP) ──────────────────
 
   describe("containerRadius (Axiom 1 child-clip cap)", () => {
-    it("default knobs are untouched (radius $4 = 9px fits medium padding 18px)", () => {
+    it("default containers use $6 = 14px inside the 16px panel padding", () => {
       const { knobProps } = resolveKnobs(defaultKnobs);
-      expect(knobProps.containerRadius).toEqual({ borderRadius: "$4" });
-      expect(knobProps.cardSurface.borderRadius).toBe("$4");
+      expect(knobProps.containerRadius).toEqual({ borderRadius: "$6" });
+      expect(knobProps.cardSurface.borderRadius).toBe("$6");
     });
 
-    it("caps full radius at the padding px for every space", () => {
-      expect(
-        resolveKnobs(knobsWith({ borderRadius: "full", space: "small" })).knobProps.containerRadius
-          .borderRadius,
-      ).toBe(13);
+    it("caps full radius at the panelPadding px of the installed scale", () => {
       expect(
-        resolveKnobs(knobsWith({ borderRadius: "full", space: "medium" })).knobProps.containerRadius
-          .borderRadius,
-      ).toBe(18);
+        resolveKnobs(knobsWith({ borderRadius: "full" })).knobProps.containerRadius.borderRadius,
+      ).toBe(16);
+      const dense = generateScale({ control: 36, type: 14 }).tokens;
       expect(
-        resolveKnobs(knobsWith({ borderRadius: "full", space: "large" })).knobProps.containerRadius
-          .borderRadius,
-      ).toBe(32);
-    });
-
-    it("only bites at large/full: none/small/medium keep their token at every space", () => {
-      for (const space of Object.values(Space)) {
-        for (const [radius, token] of [
-          ["none", "$0"],
-          ["small", "$2"],
-          ["medium", "$4"],
-        ] as const) {
-          const { knobProps } = resolveKnobs(knobsWith({ borderRadius: radius, space }));
-          expect(knobProps.containerRadius.borderRadius).toBe(token);
-        }
+        onScale(
+          36,
+          14,
+          () => resolveKnobs(knobsWith({ borderRadius: "full" })).knobProps.containerRadius,
+        ).borderRadius,
+      ).toBe(dense.space.$4);
+    });
+
+    it("caps large and full; smaller container corners keep their token", () => {
+      for (const [radius, token] of [
+        ["none", "$0"],
+        ["small", "$4"],
+        ["medium", "$6"],
+        ["large", 16],
+        ["full", 16],
+      ] as const) {
+        const { knobProps } = resolveKnobs(knobsWith({ borderRadius: radius }));
+        expect(knobProps.containerRadius.borderRadius, radius).toBe(token);
       }
     });
 
-    it("large radius caps only under small space (16px > 13px)", () => {
-      expect(
-        resolveKnobs(knobsWith({ borderRadius: "large", space: "small" })).knobProps.containerRadius
-          .borderRadius,
-      ).toBe(13);
-      expect(
-        resolveKnobs(knobsWith({ borderRadius: "large", space: "medium" })).knobProps
-          .containerRadius.borderRadius,
-      ).toBe("$6");
-      expect(
-        resolveKnobs(knobsWith({ borderRadius: "large", space: "large" })).knobProps.containerRadius
-          .borderRadius,
-      ).toBe("$6");
-    });
-
-    it("mirrored px values agree with the live @tamagui/themes tokens (drift guard)", () => {
+    it("compares generated scale px, so it agrees with the scale's own tokens (drift guard)", () => {
       const radiusTokenByKnob = {
         none: "$0",
-        small: "$2",
-        medium: "$4",
-        large: "$6",
+        small: "$4",
+        medium: "$6",
+        large: "$8",
         full: "$12",
       } as const;
-      const paddingTokenByKnob = { small: "$3", medium: "$4", large: "$6" } as const;
-      for (const [radiusKnob, radiusToken] of Object.entries(radiusTokenByKnob)) {
-        for (const [spaceKnob, paddingToken] of Object.entries(paddingTokenByKnob)) {
-          const radiusPx = (tokens.radius as any)[radiusToken.slice(1)].val as number;
-          const paddingPx = (tokens.space as any)[paddingToken.slice(1)].val as number;
+      for (const [control, type] of [
+        [40, 15],
+        [44, 15],
+        [36, 14],
+        [48, 16],
+      ] as const) {
+        const scale = generateScale({ control, type }).tokens;
+        for (const [radiusKnob, radiusToken] of Object.entries(radiusTokenByKnob)) {
+          const radiusPx = scale.radius[radiusToken.slice(1) as "0"];
+          const paddingPx = scale.space.$4;
           const expected = radiusPx > paddingPx ? paddingPx : radiusToken;
           expect(
-            capContainerRadius(radiusKnob as Knobs["borderRadius"], spaceKnob as Knobs["space"]),
-            `radius=${radiusKnob} space=${spaceKnob}`,
+            onScale(control, type, () => capContainerRadius(radiusKnob as Knobs["borderRadius"])),
+            `radius=${radiusKnob} scale=${control}/${type}`,
           ).toBe(expected);
         }
       }
     });
   });
 
+  it("containers step above controls while TextArea keeps the capped Input corner at every stop", () => {
+    for (const [borderRadius, containerPx, fieldPx] of [
+      ["none", 0, 0],
+      ["small", 8, 4],
+      ["medium", 14, 8],
+      ["large", 16, 14],
+      ["full", 16, 16],
+    ] as const) {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius }));
+      const px = (value: string | number) =>
+        typeof value === "number" ? value : defaultScaleTokens.radius[value.slice(1) as "0"];
+      const controlPx = px(knobProps.borderRadius.borderRadius);
+      expect(px(knobProps.containerRadius.borderRadius)).toBe(containerPx);
+      expect(px(knobProps.fieldRadius.borderRadius)).toBe(fieldPx);
+      expect(capFieldRadius(borderRadius)).toBe(knobProps.fieldRadius.borderRadius);
+      expect(fieldPx).toBe(Math.min(controlPx, panelPaddingPx()));
+      if (borderRadius === "none") expect(containerPx).toBe(controlPx);
+      else if (controlPx < panelPaddingPx()) expect(containerPx).toBeGreaterThan(controlPx);
+      else expect(containerPx).toBe(panelPaddingPx());
+    }
+  });
+
   // ── cornerSmoothing (Axiom 15 OPTICS) ─────────────────────
 
   describe("cornerSmoothing knob", () => {
@@ -793,13 +910,11 @@ describe("resolveKnobs", () => {
     });
 
     it("smooth keeps the Axiom 1 container cap (clamped radii keep their caps)", () => {
-      const smooth = resolveKnobs(
-        knobsWith({ cornerSmoothing: "smooth", borderRadius: "full", space: "small" }),
-      );
-      const round = resolveKnobs(knobsWith({ borderRadius: "full", space: "small" }));
-      expect(smooth.knobProps.containerRadius.borderRadius).toBe(13);
-      expect(round.knobProps.containerRadius.borderRadius).toBe(13);
-      expect(smooth.knobProps.cardSurface.borderRadius).toBe(13);
+      const smooth = resolveKnobs(knobsWith({ cornerSmoothing: "smooth", borderRadius: "full" }));
+      const round = resolveKnobs(knobsWith({ borderRadius: "full" }));
+      expect(smooth.knobProps.containerRadius.borderRadius).toBe(16);
+      expect(round.knobProps.containerRadius.borderRadius).toBe(16);
+      expect(smooth.knobProps.cardSurface.borderRadius).toBe(16);
       expect(smooth.knobProps.containerRadius.className).toBe(cornerSmoothClassName);
     });
 
@@ -965,16 +1080,16 @@ describe("resolveKnobs", () => {
         resolveKnobs(knobsWith({ headingFont: "sans-serif" })).knobProps.heading.fontFamily,
       ).toBe("$heading");
       expect(resolveKnobs(knobsWith({ headingFont: "serif" })).knobProps.heading.fontFamily).toBe(
-        "$serif",
+        "$headingSerif",
       );
       expect(resolveKnobs(knobsWith({ headingFont: "mono" })).knobProps.heading.fontFamily).toBe(
-        "$mono",
+        "$headingMono",
       );
       expect(resolveKnobs(knobsWith({ headingFont: "slab" })).knobProps.heading.fontFamily).toBe(
-        "$slab",
+        "$headingSlab",
       );
       expect(resolveKnobs(knobsWith({ headingFont: "pixel" })).knobProps.heading.fontFamily).toBe(
-        "$pixel",
+        "$headingPixel",
       );
     });
 
@@ -993,8 +1108,12 @@ describe("resolveKnobs", () => {
     });
 
     it("fontWeight maps correctly", () => {
-      expect(resolveKnobs(knobsWith({ fontWeight: "regular" })).knobProps.heading.fontWeight).toBe(
-        "400",
+      expect(
+        resolveKnobs(knobsWith({ fontWeight: "regular" })).knobProps.heading,
+      ).not.toHaveProperty("fontWeight");
+      expect(resolveKnobs(defaultKnobs).knobProps.label).not.toHaveProperty("fontWeight");
+      expect(resolveKnobs(knobsWith({ fontWeight: "bold" })).knobProps.label.fontWeight).toBe(
+        "700",
       );
       expect(resolveKnobs(knobsWith({ fontWeight: "bold" })).knobProps.heading.fontWeight).toBe(
         "700",
@@ -1005,31 +1124,31 @@ describe("resolveKnobs", () => {
   // ── pageTitleScale (D-11 hero-H1 dial) ──────────────────────
 
   describe("pageTitleScale knob", () => {
-    it("defaults to the moderate page-title step ($8 = 32px)", () => {
-      expect(resolveKnobs(defaultKnobs).knobProps.pageTitle).toEqual({ size: "$8" });
+    it("defaults to the moderate page-title step ($10 = 40px)", () => {
+      expect(resolveKnobs(defaultKnobs).knobProps.pageTitle).toEqual({ size: "$10" });
     });
 
-    it('"display" re-opens the hero step ($10 = 64px)', () => {
+    it('"display" re-opens the hero step ($12 = 52px)', () => {
       expect(resolveKnobs(knobsWith({ pageTitleScale: "display" })).knobProps.pageTitle).toEqual({
-        size: "$10",
+        size: "$12",
       });
     });
 
     it("an omitted knob still resolves moderate (preset constructions predate the dial)", () => {
       const { pageTitleScale: _omitted, ...withoutDial } = defaultKnobs;
-      expect(resolveKnobs(withoutDial as Knobs).knobProps.pageTitle).toEqual({ size: "$8" });
+      expect(resolveKnobs(withoutDial as Knobs).knobProps.pageTitle).toEqual({ size: "$10" });
     });
 
     it("resolvePageTitleScale is the one table both channels read", () => {
-      expect(resolvePageTitleScale("moderate")).toEqual({ size: "$8" });
-      expect(resolvePageTitleScale("display")).toEqual({ size: "$10" });
+      expect(resolvePageTitleScale("moderate")).toEqual({ size: "$10" });
+      expect(resolvePageTitleScale("display")).toEqual({ size: "$12" });
     });
 
     it("product presets ship moderate; `hero` is the only display opt-in", () => {
       expect(defaultPreset.knobs.pageTitleScale).toBe("moderate");
       expect(boldPreset.knobs.pageTitleScale).toBe("moderate");
       expect(heroPreset.knobs.pageTitleScale).toBe("display");
-      expect(resolveKnobs(heroPreset.knobs).knobProps.pageTitle).toEqual({ size: "$10" });
+      expect(resolveKnobs(heroPreset.knobs).knobProps.pageTitle).toEqual({ size: "$12" });
     });
 
     it("`hero` differs from the default preset in nothing but the title step", () => {
@@ -1043,6 +1162,19 @@ describe("resolveKnobs", () => {
   // ── animation ─────────────────────────────────────────────
 
   describe("animation knob", () => {
+    it("resolves each role while keeping the deprecated control alias", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ animation: "quick" }));
+      expect(knobProps.motion.control.transition).toBe("quick");
+      expect(knobProps.motion.overlay.transition).toBe("quicker");
+      expect(knobProps.motion.scrim.transition).toBe("slow");
+      expect(knobProps.motion.reveal.transition).toBe("medium");
+      expect(knobProps.motion.slide.transition).toBe("medium");
+      expect(knobProps.transition).toBe(knobProps.motion.control.transition);
+      for (const role of Object.values(
+        resolveKnobs(knobsWith({ animation: "none" })).knobProps.motion,
+      ))
+        expect(role.transition).toBeUndefined();
+    });
     it('"none" → transition is undefined', () => {
       const { knobProps } = resolveKnobs(knobsWith({ animation: "none" }));
       expect(knobProps.transition).toBeUndefined();
@@ -1078,251 +1210,26 @@ describe("resolveKnobs", () => {
       expect(overridden.knobProps.elevation).toBe("$4");
     });
 
-    // T4.1g — override callback receives knobProps with both size and space
-    it("override callback receives knobProps with both size and space", () => {
+    it("override callback receives the resolved roles and size token", () => {
       let receivedProps: KnobProps | undefined;
-      resolveKnobs(knobsWith({ size: "large", space: "small" }), (props) => {
-        receivedProps = props;
-        return {};
-      });
-      expect(receivedProps).toBeDefined();
-      expect(receivedProps!.size).toBe("large");
-      expect(receivedProps!.space).toBe("small");
-    });
-  });
-
-  // ── Group 4: Gap review tests ─────────────────────────────
-
-  describe("gap review", () => {
-    const sizeTokenMap: Record<string, string> = {
-      small: "$3",
-      medium: "$4",
-      large: "$5",
-    };
-
-    const gapMap: Record<string, string> = {
-      small: "$2",
-      medium: "$4",
-      large: "$5",
-    };
-
-    const panelPaddingMap: Record<string, string> = {
-      small: "$3",
-      medium: "$4",
-      large: "$6",
-    };
-
-    const gapLgMap: Record<string, string> = {
-      small: "$3",
-      medium: "$5",
-      large: "$6",
-    };
-
-    // T4.1a — every Size enum value produces a valid sizeToken
-    it("every Size enum value produces a valid sizeToken", () => {
-      for (const sizeVal of Object.values(Size)) {
-        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal }));
-        expect(knobProps.sizeToken).toBe(sizeTokenMap[sizeVal]);
-      }
-    });
-
-    // T4.1b — every Space enum value produces valid panelPadding, gap, gapLg
-    it("every Space enum value produces valid panelPadding, gap, gapLg", () => {
-      for (const spaceVal of Object.values(Space)) {
-        const { knobProps } = resolveKnobs(knobsWith({ space: spaceVal }));
-        expect(knobProps.panelPadding.padding).toBe(panelPaddingMap[spaceVal]);
-        expect(knobProps.gap.gap).toBe(gapMap[spaceVal]);
-        expect(knobProps.gapLg.gap).toBe(gapLgMap[spaceVal]);
-      }
-    });
-
-    // T4.1c — all 9 combinations of size × space
-    it("all 9 size × space combinations produce expected sizeToken and gap pairs", () => {
-      for (const sizeVal of Object.values(Size)) {
-        for (const spaceVal of Object.values(Space)) {
-          const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal, space: spaceVal }));
-          expect(knobProps.sizeToken).toBe(sizeTokenMap[sizeVal]);
-          expect(knobProps.gap.gap).toBe(gapMap[spaceVal]);
-          expect(knobProps.panelPadding.padding).toBe(panelPaddingMap[spaceVal]);
-          expect(knobProps.gapLg.gap).toBe(gapLgMap[spaceVal]);
-        }
-      }
-    });
-
-    // T4.1e — knobProps.space still equals knobs.space
-    it("knobProps.space equals knobs.space", () => {
-      for (const spaceVal of Object.values(Space)) {
-        const { knobProps } = resolveKnobs(knobsWith({ space: spaceVal }));
-        expect(knobProps.space).toBe(spaceVal);
-      }
-    });
-
-    // T4.1f — knobProps.size equals knobs.size
-    it("knobProps.size equals knobs.size", () => {
-      for (const sizeVal of Object.values(Size)) {
-        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal }));
-        expect(knobProps.size).toBe(sizeVal);
-      }
-    });
-
-    // T4.1h — defaultKnobs has both size and space set to "medium"
-    it('defaultKnobs has both size and space set to "medium"', () => {
-      expect(defaultKnobs.size).toBe("medium");
-      expect(defaultKnobs.space).toBe("medium");
-    });
-
-    // T4.1i — emptyStateKnobs is still valid (W12: default hover layer remains)
-    it("emptyStateKnobs is still valid (no required size field breaks it)", () => {
-      const knobs = knobsWith({ hover: emptyStateKnobs });
-      const { control } = resolveKnobs(knobs);
-      expect(control.hoverKnobProps).toEqual({ backgroundColor: "$backgroundHover" });
-    });
-
-    // T4.1j — size "large" does not change borderRadius
-    it('size "large" does not change borderRadius', () => {
-      const baseline = resolveKnobs(knobsWith({ size: "medium" }));
-      const large = resolveKnobs(knobsWith({ size: "large" }));
-      expect(large.knobProps.borderRadius).toEqual(baseline.knobProps.borderRadius);
+      resolveKnobs(
+        defaultKnobs,
+        (props) => {
+          receivedProps = props;
+          return {};
+        },
+        "light",
+        { sizeToken: "$3" },
+      );
+      expect(receivedProps!.sizeToken).toBe("$3");
+      expect(receivedProps!.gap).toEqual({ gap: "$3" });
     });
   });
-});
-
-// ── Density (DG-DEN-01 / W8) ─────────────────────────────────
-
-describe("applyDensity", () => {
-  it('defaultKnobs.density is "comfortable"', () => {
-    expect(defaultKnobs.density).toBe(Density.Comfortable);
-  });
 
-  it("comfortable density leaves size and space unchanged", () => {
-    const knobs = knobsWith({ size: "large", space: "large", density: "comfortable" });
-    const applied = applyDensity(knobs);
-    expect(applied.size).toBe("large");
-    expect(applied.space).toBe("large");
-    expect(applied.density).toBe("comfortable");
-  });
-
-  it("compact density steps space down one level and leaves size unchanged", () => {
-    expect(
-      applyDensity(knobsWith({ size: "large", space: "large", density: "compact" })),
-    ).toMatchObject({ size: "large", space: "medium", density: "compact" });
-    expect(
-      applyDensity(knobsWith({ size: "medium", space: "medium", density: "compact" })),
-    ).toMatchObject({ size: "medium", space: "small", density: "compact" });
-    expect(
-      applyDensity(knobsWith({ size: "small", space: "small", density: "compact" })),
-    ).toMatchObject({ size: "small", space: "small", density: "compact" });
-  });
-
-  it("compact:true override wins over comfortable density knob without changing size", () => {
-    const applied = applyDensity(
-      knobsWith({ size: "medium", space: "medium", density: "comfortable" }),
-      true,
-    );
-    expect(applied).toMatchObject({ size: "medium", space: "small", density: "compact" });
-  });
-
-  it("compact:false override wins over compact density knob", () => {
-    const applied = applyDensity(
-      knobsWith({ size: "medium", space: "medium", density: "compact" }),
-      false,
-    );
-    expect(applied).toMatchObject({ size: "medium", space: "medium", density: "comfortable" });
-  });
-
-  it("resolveKnobs exposes density on knobProps", () => {
-    expect(resolveKnobs(defaultKnobs).knobProps.density).toBe("comfortable");
-    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` retains the size-table grouping across density and shape.
-    // 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(
-      applyDensity(knobsWith({ size: "medium", space: "medium", density: "compact" })),
-    );
-    expect(comfortable.knobProps.sizeToken).toBe("$4");
-    expect(compact.knobProps.sizeToken).toBe("$4");
-    expect(compact.knobProps.control.height).toBe(comfortable.knobProps.control.height);
-    expect(comfortable.knobProps.gap).toEqual({ gap: "$4" });
-    expect(compact.knobProps.gap).toEqual({ gap: "$2" });
-  });
-
-  it("pairs label type to size — never the control-height sizeToken", () => {
-    expect(resolveKnobs(knobsWith({ size: "small" })).knobProps.label.fontSize).toBe("$2");
-    expect(resolveKnobs(knobsWith({ size: "medium" })).knobProps.label.fontSize).toBe("$3");
-    expect(resolveKnobs(knobsWith({ size: "large" })).knobProps.label.fontSize).toBe("$4");
-    expect(resolveKnobs(defaultKnobs).knobProps.label.fontSize).not.toBe(
-      resolveKnobs(defaultKnobs).knobProps.sizeToken,
-    );
-  });
-
-  it("nestedControl paints below the 44px floor and restores press with hitSlop", () => {
-    const medium = resolveKnobs(knobsWith({ size: "medium" })).knobProps.nestedControl;
-    expect(medium.px).toBe(32);
-    expect(medium.width).toBe(32);
-    expect(medium.maxWidth).toBe(32);
-    expect(medium.hitSlop).toEqual({ top: 6, bottom: 6, left: 6, right: 6 });
-
-    const compact = resolveKnobs(applyDensity(knobsWith({ size: "medium", density: "compact" })))
-      .knobProps.nestedControl;
-    // Compact steps space only (LC-76) — nestedControl follows size, so
-    // medium+compact stays on the medium nested box.
-    expect(compact.px).toBe(32);
-    expect(compact.hitSlop).toEqual({ top: 6, bottom: 6, left: 6, right: 6 });
-  });
-
-  it("compact density preserves house-decision knobs", () => {
-    const knobs = knobsWith({
-      density: "compact",
-      fieldLabelPlacement: "side",
-      requiredMarking: "asterisk",
-      tableZebra: "on",
-      bulkBarPlacement: "bottom",
-      selectAllScope: "filtered",
-      timestampStyle: "relative",
-      disabledStyle: "dimWhole",
-      formAutofocus: "on",
-    });
-    const applied = applyDensity(knobs);
-    expect(applied).toMatchObject({
-      density: "compact",
-      fieldLabelPlacement: "side",
-      requiredMarking: "asterisk",
-      tableZebra: "on",
-      bulkBarPlacement: "bottom",
-      selectAllScope: "filtered",
-      timestampStyle: "relative",
-      disabledStyle: "dimWhole",
-      formAutofocus: "on",
-    });
+  it("emptyStateKnobs is still valid (W12: default hover layer remains)", () => {
+    const knobs = knobsWith({ hover: emptyStateKnobs });
+    const { control } = resolveKnobs(knobs);
+    expect(control.hoverKnobProps).toEqual({ backgroundColor: "$backgroundHover" });
   });
 });
 
@@ -1387,7 +1294,7 @@ describe("house decision knobs", () => {
     expect(housey.knobProps.sizeToken).toBe(baseline.knobProps.sizeToken);
     expect(housey.knobProps.gap).toEqual(baseline.knobProps.gap);
     expect(housey.knobProps.borderRadius).toEqual(baseline.knobProps.borderRadius);
-    expect(housey.knobProps.density).toBe(baseline.knobProps.density);
+    expect(housey.knobProps.panelPadding).toEqual(baseline.knobProps.panelPadding);
   });
 });
 
@@ -1481,11 +1388,11 @@ describe("LC-67 touch height floor via resolveKnobs", () => {
     }));
     const { resolveKnobs: resolveTouch } = await import("./resolveKnobs");
     try {
-      const small = resolveTouch(knobsWith({ size: "small" }));
-      const medium = resolveTouch(knobsWith({ size: "medium" }));
+      const small = resolveTouch(defaultKnobs, undefined, "light", { sizeToken: "$3" });
+      const medium = resolveTouch(defaultKnobs);
       expect(small.knobProps.control.height).toBeGreaterThanOrEqual(44);
       expect(medium.knobProps.control.height).toBeGreaterThanOrEqual(44);
-      expect(medium.knobProps.control.height).toBeGreaterThan(small.knobProps.control.height);
+      expect(medium.knobProps.control.height).toBe(small.knobProps.control.height);
     } finally {
       vi.doUnmock("@multiplatform.one/platform");
       vi.resetModules();
@@ -1495,16 +1402,49 @@ describe("LC-67 touch height floor via resolveKnobs", () => {
 
 describe("containerCapProps (DG-RAD-04 provenance)", () => {
   it("names the knob stop a borderRadiusMap token came from", () => {
-    expect(containerCapProps("PageSection", "$12", "small")).toEqual({
+    expect(containerCapProps("PageSection", "$12")).toEqual({
       "data-constraint-container": "PageSection",
       "data-radius-knob": "full",
-      "data-space-knob": "small",
     });
   });
 
+  it("decodes control tokens even when a container uses a larger key", () => {
+    expect(containerCapProps("PageSection", "$4")?.["data-radius-knob"]).toBe("medium");
+    expect(containerCapProps("TextArea", "$6")?.["data-radius-knob"]).toBe("large");
+    expect(containerCapProps("PageSection", "$8")).toBeUndefined();
+  });
+
   it("makes no claim for a radius that did not come from the knob", () => {
-    expect(containerCapProps("TextArea", 13, "small")).toBeUndefined();
-    expect(containerCapProps("TextArea", "$5", "small")).toBeUndefined();
-    expect(containerCapProps("TextArea", "$12", "roomy")).toBeUndefined();
+    expect(containerCapProps("TextArea", 13)).toBeUndefined();
+    expect(containerCapProps("TextArea", "$5")).toBeUndefined();
+  });
+});
+
+describe("painted ancestor (WP-c2: nested surfaces stop re-elevating)", () => {
+  const knobs = { ...defaultKnobs, elevation: "large" as const };
+
+  it("top level: elevatedSurface carries the overlay elevation and paint", () => {
+    const { knobProps } = resolveKnobs(knobs);
+    expect(knobProps.elevatedSurface.elevation).toBe(knobProps.overlayElevation);
+    expect(knobProps.elevatedSurface.shadowRadius).toBeGreaterThan(0);
+    expect(knobProps.cardSurface.backgroundColor).toBe("$background");
+  });
+
+  it("under a painted ancestor: elevatedSurface is border only, cardSurface one step off", () => {
+    const { knobProps } = resolveKnobs(knobs, undefined, "light", { painted: true });
+    expect(knobProps.elevatedSurface.elevation).toBeUndefined();
+    expect(knobProps.elevatedSurface.shadowRadius).toBeUndefined();
+    expect(knobProps.elevatedSurface.style).toBeUndefined();
+    expect(knobProps.elevatedSurface.borderWidth).toBeGreaterThan(0);
+    expect(knobProps.elevatedSurface.borderColor).toBe("$borderColor");
+    expect(knobProps.cardSurface.backgroundColor).toBe(paintedCardFill);
+    expect(paintedCardFill).toBe("$color2");
+  });
+
+  it("border only survives borderWidth none: the hairline floor still draws the box", () => {
+    const { knobProps } = resolveKnobs({ ...knobs, borderWidth: "none" }, undefined, "light", {
+      painted: true,
+    });
+    expect(knobProps.elevatedSurface.borderWidth).toBeGreaterThan(0);
   });
 });