@multiplatform.one/theme 7.34.4 → 7.36.0

package/src/figma/figmaTokens.spec.ts

@@ -1,5 +1,6 @@
 import * as Colors from "@tamagui/colors";
-import { defaultConfig } from "@tamagui/config/v5";
+import { generateScale } from "../theme/scale/generateScale";
+import { defaultScaleInputs } from "../theme/scale/scaleInputs";
 import { describe, expect, it } from "vitest";
 import { normalizeToHex } from "../theme/colorRules";
 import { defaultAccentTheme } from "../theme/defaults/accent";
@@ -57,8 +58,12 @@ describe("buildFigmaTokens", () => {
           expect(sameColor(built[i], source[i])).toBe(true);
         }
       }
-      expect(defaultAccentTheme.lightPalette).toContain(result.palette.themes.accent.light[0]);
-      expect(defaultAccentTheme.darkPalette).toContain(result.palette.themes.accent.dark[0]);
+      expect(
+        sameColor(defaultAccentTheme.lightPalette[0], result.palette.themes.accent.light[0]),
+      ).toBe(true);
+      expect(
+        sameColor(defaultAccentTheme.darkPalette[0], result.palette.themes.accent.dark[0]),
+      ).toBe(true);
     });
 
     it("derives intent ramps from @tamagui/colors (error=red, success=green, warning=yellow)", () => {
@@ -96,7 +101,7 @@ describe("buildFigmaTokens", () => {
       // borderColor back off color5, the background states no longer forced.
       expect(result.semantic.borderColor?.alias).toBe("color4");
       expect(result.semantic.textMuted?.alias).toBe("color11");
-      expect(result.semantic.placeholderColor?.alias).toBe("color10");
+      expect(result.semantic.placeholderColor?.alias).toBe("color9");
       expect(result.semantic.surfaceMuted?.alias).toBe("color10");
       expect(result.semantic.borderStrong?.alias).toBe("color7");
     });
@@ -135,17 +140,12 @@ describe("buildFigmaTokens", () => {
   });
 
   describe("sizing", () => {
-    it("mirrors the v5 defaultConfig tokens with figma-safe names", () => {
-      // Read against the ERA the package pins (MPO-19 X13), not against a
-      // transcribed table: v5 keys carry the `$`, values are raw numbers.
-      const size = defaultConfig.tokens.size as Record<string, number>;
+    it("mirrors the generated default tokens with figma-safe names", () => {
+      const tokens = generateScale(defaultScaleInputs).tokens;
+      const size = tokens.size as Record<string, number>;
       expect(result.sizing["size-true"]).toBe(size.$true);
-      expect(result.sizing["radius-4"]).toBe(
-        (defaultConfig.tokens.radius as Record<string, number>)["4"],
-      );
-      expect(result.sizing["space-1-5"]).toBe(
-        (defaultConfig.tokens.space as Record<string, number>)["$1.5"],
-      );
+      expect(result.sizing["radius-4"]).toBe((tokens.radius as Record<string, number>)["4"]);
+      expect(result.sizing["space-1-5"]).toBe((tokens.space as Record<string, number>)["$1.5"]);
     });
 
     it("exports knob-shaped borderWidth values including the 0.5 hairline", () => {
@@ -188,31 +188,23 @@ describe("buildFigmaTokens", () => {
       expect(modes.large.sizeToken).toBe("$4");
     });
 
-    it("exports fontWeight, space, size and cornerSmoothing modes", () => {
+    it("exports fontWeight and cornerSmoothing modes", () => {
       expect(result.knobs.fontWeight.modes).toEqual({ regular: "400", bold: "700" });
-      expect(result.knobs.space.modes.medium.paddingFigmaName).toBe("space-4");
-      expect(result.knobs.space.modes.medium.gapFigmaName).toBe("space-4");
-      expect(result.knobs.space.modes.medium.gapLgFigmaName).toBe("space-5");
-      expect(result.knobs.size.modes).toEqual({
-        small: { token: "$3", figmaName: "size-3" },
-        medium: { token: "$4", figmaName: "size-4" },
-        large: { token: "$5", figmaName: "size-5" },
-      });
       expect(result.knobs.cornerSmoothing.modes).toEqual({ round: 0, smooth: 0.6 });
     });
 
-    it("exports density compact stepping for space only (size is uncoupled)", () => {
-      expect(result.knobs.density.default).toBe("comfortable");
-      expect(result.knobs.density.compact.size).toEqual({
-        small: "small",
-        medium: "medium",
-        large: "large",
-      });
-      expect(result.knobs.density.compact.space).toEqual({
-        small: "small",
-        medium: "small",
-        large: "medium",
+    it("exports the spacing roles and the default size token, not size/space/density modes", () => {
+      expect(result.knobs.spacing).toEqual({
+        gapSm: { token: "$2", figmaName: "space-2" },
+        gap: { token: "$3", figmaName: "space-3" },
+        gapLg: { token: "$5", figmaName: "space-5" },
+        panelPadding: { token: "$4", figmaName: "space-4" },
+        featurePadding: { token: "$6", figmaName: "space-6" },
       });
+      expect(result.knobs.sizeToken).toEqual({ token: "$true", figmaName: "size-true" });
+      expect(result.knobs).not.toHaveProperty("space");
+      expect(result.knobs).not.toHaveProperty("size");
+      expect(result.knobs).not.toHaveProperty("density");
     });
   });
 

package/src/figma/figmaTokens.ts

@@ -13,8 +13,8 @@
  *   the built base themes (a key only becomes a `colorN` alias when light
  *   AND dark agree on the step index; otherwise raw per-scheme values are
  *   exported).
- * - Sizing: `tokens` from `@tamagui/themes` (the tokens
- *   `createDefaultThemeConfig` installs).
+ * - Sizing: the default generated scale (`generateScale`), the tokens
+ *   `createDefaultThemeConfig` installs.
  * - Knob outputs: `resolveKnobs()` is executed per knob mode — the export
  *   shows exactly what the runtime resolver produces.
  * - Typography: the built `defaultHeadingFont` / `defaultBodyFont` tables
@@ -25,14 +25,18 @@
  * stamps `generatedAt` when writing to disk.
  */
 
-import { tokens } from "@tamagui/themes";
+import { createTokens } from "@tamagui/web";
 import { createThemesBuilder, tintHueNames } from "../theme/createThemes";
 import { defaultAccentTheme } from "../theme/defaults/accent";
 import { defaultBaseTheme } from "../theme/defaults/base";
 import { defaultBuilderOptions } from "../theme/defaults/builderOptions";
 import { defaultBodyFont, defaultHeadingFont } from "../theme/defaults/fonts";
 import { type Knobs, defaultKnobs } from "../theme/knobs";
-import { compactSpaceMap, resolveKnobs } from "../theme/resolveKnobs";
+import { resolveKnobs, spacingRoles } from "../theme/resolveKnobs";
+import { generateScale } from "../theme/scale/generateScale";
+import { defaultScaleInputs } from "../theme/scale/scaleInputs";
+
+const tokens = createTokens(generateScale(defaultScaleInputs).tokens);
 
 // ── Names / constants ─────────────────────────────────────────
 
@@ -105,13 +109,10 @@ export interface FigmaElevationMode {
   px: number | null;
 }
 
-export interface FigmaSpaceMode {
-  paddingToken: string;
-  paddingFigmaName: string;
-  gapToken: string;
-  gapFigmaName: string;
-  gapLgToken: string;
-  gapLgFigmaName: string;
+/** One spacing role: a fixed `$space` key whose px the scale supplies. */
+export interface FigmaSpacingRole {
+  token: string;
+  figmaName: string;
 }
 
 export interface FigmaKnobsExport {
@@ -119,14 +120,11 @@ export interface FigmaKnobsExport {
   borderWidth: { default: Knobs["borderWidth"]; modes: Record<string, number> };
   elevation: { default: Knobs["elevation"]; modes: Record<string, FigmaElevationMode> };
   fontWeight: { default: Knobs["fontWeight"]; modes: Record<string, string> };
-  space: { default: Knobs["space"]; modes: Record<string, FigmaSpaceMode> };
-  size: { default: Knobs["size"]; modes: Record<string, { token: string; figmaName: string }> };
   cornerSmoothing: { default: string; modes: Record<string, number> };
-  density: {
-    default: Knobs["density"];
-    /** compact steps space only (applyDensity); size is an independent axis. */
-    compact: { size: Record<string, string>; space: Record<string, string> };
-  };
+  /** SP-GAP roles: fixed `$space` keys, not knob modes. */
+  spacing: Record<keyof typeof spacingRoles, FigmaSpacingRole>;
+  /** The control size token at the default (`$true`); a use site picks another with `size`. */
+  sizeToken: FigmaSpacingRole;
 }
 
 export interface FigmaFontExport {
@@ -288,7 +286,7 @@ function buildSizing(borderWidthModes: Record<string, number>): Record<string, n
   ];
   for (const [prefix, group] of groups) {
     if (prefix !== "zIndex" && Object.keys(group).length === 0) {
-      throw new Error(`figmaTokens: @tamagui/themes tokens.${prefix} is empty`);
+      throw new Error(`figmaTokens: generated tokens.${prefix} is empty`);
     }
     for (const [key, val] of Object.entries(group)) {
       sizing[figmaTokenName(prefix, key)] = val;
@@ -306,8 +304,6 @@ const RADIUS_KNOB_MODES: Knobs["borderRadius"][] = ["none", "small", "medium", "
 const BORDER_WIDTH_KNOB_MODES: Knobs["borderWidth"][] = ["none", "small", "medium", "large"];
 const ELEVATION_KNOB_MODES: Knobs["elevation"][] = ["none", "small", "medium", "large"];
 const FONT_WEIGHT_KNOB_MODES: Knobs["fontWeight"][] = ["regular", "bold"];
-const SPACE_KNOB_MODES: Knobs["space"][] = ["small", "medium", "large"];
-const SIZE_KNOB_MODES: Knobs["size"][] = ["small", "medium", "large"];
 
 function radiusPx(token: string): number {
   const radius = unwrapTokenGroup(tokens.radius);
@@ -373,47 +369,27 @@ function buildKnobs(): FigmaKnobsExport {
     fontWeight[mode] = String(knobProps.textWeight.fontWeight);
   }
 
-  const space: Record<string, FigmaSpaceMode> = {};
-  for (const mode of SPACE_KNOB_MODES) {
-    const { knobProps } = resolveKnobs({ ...defaultKnobs, space: mode });
-    const paddingToken = String(knobProps.panelPadding.padding);
-    const gapToken = String(knobProps.gap.gap);
-    const gapLgToken = String(knobProps.gapLg.gap);
-    space[mode] = {
-      paddingToken,
-      paddingFigmaName: tokenToFigma(paddingToken, "space"),
-      gapToken,
-      gapFigmaName: tokenToFigma(gapToken, "space"),
-      gapLgToken,
-      gapLgFigmaName: tokenToFigma(gapLgToken, "space"),
-    };
+  const spacing = {} as Record<keyof typeof spacingRoles, FigmaSpacingRole>;
+  for (const [role, token] of Object.entries(spacingRoles) as [
+    keyof typeof spacingRoles,
+    string,
+  ][]) {
+    spacing[role] = { token, figmaName: tokenToFigma(token, "space") };
   }
 
-  const size: Record<string, { token: string; figmaName: string }> = {};
-  for (const mode of SIZE_KNOB_MODES) {
-    const { knobProps } = resolveKnobs({ ...defaultKnobs, size: mode });
-    const token = String(knobProps.sizeToken);
-    size[mode] = { token, figmaName: tokenToFigma(token, "size") };
-  }
+  const sizeToken = String(resolveKnobs(defaultKnobs).knobProps.sizeToken);
 
   return {
     borderRadius: { default: defaultKnobs.borderRadius, modes: borderRadius },
     borderWidth: { default: defaultKnobs.borderWidth, modes: borderWidth },
     elevation: { default: defaultKnobs.elevation, modes: elevation },
     fontWeight: { default: defaultKnobs.fontWeight, modes: fontWeight },
-    space: { default: defaultKnobs.space, modes: space },
-    size: { default: defaultKnobs.size, modes: size },
     cornerSmoothing: {
       default: defaultKnobs.cornerSmoothing ?? "round",
       modes: { ...FIGMA_CORNER_SMOOTHING },
     },
-    density: {
-      default: defaultKnobs.density,
-      compact: {
-        size: { small: "small", medium: "medium", large: "large" },
-        space: { ...compactSpaceMap },
-      },
-    },
+    spacing,
+    sizeToken: { token: sizeToken, figmaName: tokenToFigma(sizeToken, "size") },
   };
 }
 

package/src/fonts/createFontLoader.ts

@@ -3,7 +3,10 @@ import type { FontLoader, FontLoaderConfig } from "./types";
 export function createFontLoader(config: FontLoaderConfig): FontLoader {
   const fontMap: Record<string, number> = {};
   if (config.inter) {
-    fontMap.Inter = require("@tamagui/font-inter/otf/Inter-Medium.otf");
+    fontMap.Inter = require("@tamagui/font-inter/otf/Inter-Regular.otf");
+    fontMap.InterMedium = require("@tamagui/font-inter/otf/Inter-Medium.otf");
+    fontMap.InterSemiBold = require("@tamagui/font-inter/otf/Inter-SemiBold.otf");
+    fontMap.InterExtraBold = require("@tamagui/font-inter/otf/Inter-ExtraBold.otf");
     fontMap.InterBold = require("@tamagui/font-inter/otf/Inter-Bold.otf");
   }
   for (const font of config.fonts) {

package/src/menuRow.ts

@@ -18,7 +18,10 @@
  * - color ramps: menus highlight with `componentColors.interactive.*`,
  *   form fields with `formInputColors.background.*` (package-boundary rule);
  * - cursor: `pointer` for menu items, `default` for listbox options;
- * - vertical sizing: height/minHeight from the size token, or row padding;
+ * - vertical sizing: spread `knobProps.menuRow` (the `menuRow` recipe
+ *   family — one size key below the control token, 36 at default, 44 on
+ *   touch, padX `$3`); Select reads `knobProps.menuRow.minHeight` as its row
+ *   pitch. MentionInput keeps its own suggestion pitch;
  * - in-row gap and the state-variant model (selected/active/disabled).
  */
 export const menuRowFrame = {

package/src/theme/FontKnobStyles.tsx

@@ -209,6 +209,7 @@ export function FontKnobStyles() {
   const knobs = presetCtx ? { ...presetCtx.preset.knobs, ...presetCtx.overrides } : defaultKnobs;
   const headingFont = knobs.headingFont ?? defaultKnobs.headingFont;
   const bodyFont = knobs.bodyFont ?? defaultKnobs.bodyFont;
+  const scaleId = presetCtx?.scaleId;
 
   useEffect(() => {
     if (typeof document === "undefined") return;
@@ -224,7 +225,7 @@ export function FontKnobStyles() {
       document.head.appendChild(tag);
     }
     if (tag.textContent !== css) tag.textContent = css;
-  }, [headingFont, bodyFont]);
+  }, [headingFont, bodyFont, scaleId]);
 
   useEffect(
     () => () => {

package/src/theme/Preset.stories.tsx

@@ -22,7 +22,6 @@ function Probe({ label }: { label: string }) {
     "data-border-radius": String(knobProps.borderRadius.borderRadius),
     "data-border-width": String(knobProps.surface.borderWidth),
     "data-fill-style": knobProps.outlined ? "outlined" : "filled",
-    "data-space": String(knobProps.space),
   } as Record<string, unknown>;
   return (
     <YStack

package/src/theme/Preset.tsx

@@ -51,6 +51,8 @@ export function Preset({
           knobs: { ...base.knobs, ...parentCtx.overrides, ...overrides },
         },
         overrides: Object.keys(mergedOverrides).length > 0 ? mergedOverrides : undefined,
+        presetName: parentCtx.presetName,
+        scaleId: parentCtx.scaleId,
       };
     }
 
@@ -72,14 +74,17 @@ export function Preset({
       base = freshDefault;
     }
 
+    const scope = { presetName: parentCtx?.presetName, scaleId: parentCtx?.scaleId };
+
     if (overrides) {
       return {
         preset: { ...base, knobs: { ...base.knobs, ...overrides } },
         overrides,
+        ...scope,
       };
     }
 
-    return { preset: base };
+    return { preset: base, ...scope };
   }, [cascade, parentCtx, presetName, overrides]);
 
   let element = <PresetContext.Provider value={ctxValue}>{children}</PresetContext.Provider>;

package/src/theme/PresetContext.ts

@@ -6,6 +6,10 @@ import type { ThemeName } from "@tamagui/web";
 export interface PresetContextValue {
   preset: Preset;
   overrides?: Partial<Knobs>;
+  /** Name of the provider's active preset, whose scale is installed. */
+  presetName?: string;
+  /** Id of the installed token scale; changes after a switch re-render every knob reader. */
+  scaleId?: string;
 }
 
 export const PresetContext = createContext<PresetContextValue | null>(null);

package/src/theme/Surface.spec.tsx

@@ -1,16 +1,23 @@
 import { TestProviders } from "@multiplatform.one/test-utils";
 /**
- * Surface context — nested size/density step-down (LC-68).
+ * Surface context: a forwarded size token with a step-down ceiling (LC-78).
  */
 
 import { render, renderHook } from "@testing-library/react";
 import { createElement, type ReactNode } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SizeTokens } from "tamagui";
+import { generateScale } from "./scale/generateScale";
+import { defaultScaleInputs } from "./scale/scaleInputs";
 import {
   Surface,
   SurfaceContext,
-  clampSurfaceDensity,
   clampSurfaceSize,
+  compareSizeTokens,
+  sizeTokenStep,
+  sizeTokenBelow,
+  sizeTokenStop,
+  surfaceSizeRank,
   type SurfaceIntent,
 } from "./Surface";
 import { useResolvedKnobs } from "./useResolvedKnobs";
@@ -44,114 +51,154 @@ function Probe({ onRead }: { onRead: (intent: SurfaceIntent) => void }) {
   return null;
 }
 
-function renderNested(
-  outer: { size?: "small" | "medium" | "large"; density?: "compact" | "comfortable" },
-  inner: { size?: "small" | "medium" | "large"; density?: "compact" | "comfortable" },
-): SurfaceIntent {
+function renderNested(outer: SizeTokens | undefined, inner: SizeTokens | undefined): SurfaceIntent {
   let intent: SurfaceIntent | undefined;
   render(
     createElement(
       Surface,
-      outer,
-      createElement(Surface, inner, createElement(Probe, { onRead: (value) => (intent = value) })),
+      { size: outer },
+      createElement(
+        Surface,
+        { size: inner },
+        createElement(Probe, { onRead: (value) => (intent = value) }),
+      ),
     ),
   );
   if (!intent) throw new Error("Surface probe did not render");
   return intent;
 }
 
-describe("clampSurfaceSize", () => {
-  it("unset parent is no ceiling", () => {
-    expect(clampSurfaceSize("large", "unset")).toBe("large");
-    expect(clampSurfaceSize("unset", "unset")).toBe("unset");
+const scale = generateScale(defaultScaleInputs).tokens;
+
+describe("surfaceSizeRank", () => {
+  it("ranks size keys by the scale's sorted $size ladder; $true ranks with $4", () => {
+    expect(surfaceSizeRank("$2")!).toBeLessThan(surfaceSizeRank("$3")!);
+    expect(surfaceSizeRank("$3")!).toBeLessThan(surfaceSizeRank("$3.5")!);
+    expect(surfaceSizeRank("$3.5")!).toBeLessThan(surfaceSizeRank("$4")!);
+    expect(surfaceSizeRank("$true")).toBe(surfaceSizeRank("$4"));
+    expect(surfaceSizeRank("$5")!).toBeGreaterThan(surfaceSizeRank("$4")!);
   });
 
-  it("unset requested inherits parent", () => {
-    expect(clampSurfaceSize("unset", "small")).toBe("small");
-    expect(clampSurfaceSize("unset", "large")).toBe("large");
+  it("does not rank anything that is not a size key (no sm/md/lg aliases)", () => {
+    for (const alias of ["sm", "small", "md", "medium", "lg", "large"]) {
+      expect(surfaceSizeRank(alias as SizeTokens), alias).toBeUndefined();
+    }
   });
+});
 
-  it("never exceeds parent", () => {
-    expect(clampSurfaceSize("large", "small")).toBe("small");
-    expect(clampSurfaceSize("medium", "small")).toBe("small");
-    expect(clampSurfaceSize("large", "medium")).toBe("medium");
+describe("compareSizeTokens", () => {
+  it("orders size keys on the ladder and treats anything else as equal", () => {
+    expect(compareSizeTokens("$3", "$true")).toBeLessThan(0);
+    expect(compareSizeTokens("$5", "$4")).toBeGreaterThan(0);
+    expect(compareSizeTokens("$4", "$true")).toBe(0);
+    expect(compareSizeTokens("small", "$true")).toBe(0);
   });
 
-  it("tighter than parent is allowed", () => {
-    expect(clampSurfaceSize("small", "large")).toBe("small");
-    expect(clampSurfaceSize("medium", "large")).toBe("medium");
-    expect(clampSurfaceSize("small", "medium")).toBe("small");
+  it("sizeTokenStep says which side of the default control size a token sits", () => {
+    expect(sizeTokenStep("$3")).toBe(-1);
+    expect(sizeTokenStep("$true")).toBe(0);
+    expect(sizeTokenStep("$4")).toBe(0);
+    expect(sizeTokenStep("$6")).toBe(1);
+    expect([sizeTokenStop("$3"), sizeTokenStop("$true"), sizeTokenStop("$5")]).toEqual([
+      "small",
+      "medium",
+      "large",
+    ]);
   });
 });
 
-describe("clampSurfaceDensity", () => {
+describe("clampSurfaceSize", () => {
   it("unset parent is no ceiling", () => {
-    expect(clampSurfaceDensity("comfortable", "unset")).toBe("comfortable");
+    expect(clampSurfaceSize("$5", "unset")).toBe("$5");
+    expect(clampSurfaceSize("unset", "unset")).toBe("unset");
   });
 
   it("unset requested inherits parent", () => {
-    expect(clampSurfaceDensity("unset", "compact")).toBe("compact");
+    expect(clampSurfaceSize("unset", "$3")).toBe("$3");
+    expect(clampSurfaceSize("unset", "$5")).toBe("$5");
   });
 
-  it("never exceeds parent; tighter is allowed", () => {
-    expect(clampSurfaceDensity("comfortable", "compact")).toBe("compact");
-    expect(clampSurfaceDensity("compact", "comfortable")).toBe("compact");
+  it("never exceeds parent", () => {
+    expect(clampSurfaceSize("$5", "$3")).toBe("$3");
+    expect(clampSurfaceSize("$4", "$3")).toBe("$3");
+    expect(clampSurfaceSize("$true", "$3")).toBe("$3");
+    expect(clampSurfaceSize("$5", "$true")).toBe("$true");
+  });
+
+  it("smaller than parent is allowed", () => {
+    expect(clampSurfaceSize("$3", "$5")).toBe("$3");
+    expect(clampSurfaceSize("$2", "$true")).toBe("$2");
+    expect(clampSurfaceSize("$true", "$4")).toBe("$true");
+  });
+
+  it("an unranked request under a ceiling takes the ceiling", () => {
+    expect(clampSurfaceSize(40 as SizeTokens, "$3")).toBe("$3");
   });
 });
 
-describe("Surface nesting (LC-68)", () => {
-  it("nested Surface size large inside small resolves small", () => {
-    expect(renderNested({ size: "small" }, { size: "large" }).size).toBe("small");
+describe("Surface nesting (LC-78)", () => {
+  it("nested $5 inside $3 resolves $3", () => {
+    expect(renderNested("$3", "$5").size).toBe("$3");
   });
 
-  it("nested comfortable inside compact resolves compact", () => {
-    expect(renderNested({ density: "compact" }, { density: "comfortable" }).density).toBe(
-      "compact",
-    );
+  it("nested $3 inside $5 resolves $3 (smaller allowed)", () => {
+    expect(renderNested("$5", "$3").size).toBe("$3");
   });
 
-  it("nested small inside large resolves small (tighter allowed)", () => {
-    expect(renderNested({ size: "large" }, { size: "small" }).size).toBe("small");
+  it("an unset inner Surface inherits the outer token", () => {
+    expect(renderNested("$3", undefined).size).toBe("$3");
+  });
+
+  it("the context carries only a size: no density", () => {
+    expect(renderNested("$3", undefined)).not.toHaveProperty("density");
   });
 });
 
 describe("useResolvedKnobs inside Surface", () => {
-  it("size=small density=compact → sizeToken $3, compact gap, small desktop control height", () => {
-    const wrapper = ({ children }: { children: ReactNode }) =>
-      createElement(
-        TestProviders,
-        null,
-        createElement(Surface, { size: "small", density: "compact" }, children),
-      );
-    const { result } = renderHook(() => useResolvedKnobs(), { wrapper });
-    expect(result.current.knobProps.size).toBe("small");
+  const inSurface =
+    (size: SizeTokens) =>
+    ({ children }: { children: ReactNode }) =>
+      createElement(TestProviders, null, createElement(Surface, { size }, children));
+
+  it('<Surface size="$3"> renders controls at the scale\'s $3 height', () => {
+    const { result } = renderHook(() => useResolvedKnobs(), { wrapper: inSurface("$3") });
     expect(result.current.knobProps.sizeToken).toBe("$3");
-    expect(result.current.knobProps.density).toBe("compact");
-    expect(result.current.knobProps.gap).toEqual({ gap: "$2" });
-    expect(result.current.knobProps.control.height).toBe(36);
+    expect(result.current.knobProps.control.height).toBe(scale.size.$3);
+    expect(result.current.knobProps.label.fontSize).toBe("$3");
   });
 
-  it("a large size request inside a medium Surface resolves medium", () => {
-    const wrapper = ({ children }: { children: ReactNode }) =>
-      createElement(TestProviders, null, createElement(Surface, { size: "medium" }, children));
-    const { result } = renderHook(() => useResolvedKnobs({ size: "$5" }), { wrapper });
-    expect(result.current.knobProps.size).toBe("medium");
-    expect(result.current.knobProps.sizeToken).toBe("$4");
+  it('a size="$5" request inside <Surface size="$3"> clamps to $3', () => {
+    const { result } = renderHook(() => useResolvedKnobs({ size: "$5" }), {
+      wrapper: inSurface("$3"),
+    });
+    expect(result.current.knobProps.sizeToken).toBe("$3");
+    expect(result.current.knobProps.control.height).toBe(scale.size.$3);
   });
 
-  it("Surface size is inherited as the subtree default (lg over global medium)", () => {
-    const wrapper = ({ children }: { children: ReactNode }) =>
-      createElement(TestProviders, null, createElement(Surface, { size: "lg" }, children));
-    const { result } = renderHook(() => useResolvedKnobs(), { wrapper });
-    expect(result.current.knobProps.size).toBe("large");
+  it("a smaller request inside the Surface keeps its own token", () => {
+    const { result } = renderHook(() => useResolvedKnobs({ size: "$2" }), {
+      wrapper: inSurface("$3"),
+    });
+    expect(result.current.knobProps.sizeToken).toBe("$2");
+    expect(result.current.knobProps.control.height).toBe(scale.size.$2);
+  });
+
+  it("the Surface token is the subtree default, and the spacing roles do not move", () => {
+    const { result } = renderHook(() => useResolvedKnobs(), { wrapper: inSurface("$5") });
     expect(result.current.knobProps.sizeToken).toBe("$5");
+    expect(result.current.knobProps.control.height).toBe(scale.size.$5);
+    expect(result.current.knobProps.gap).toEqual({ gap: "$3" });
+    expect(result.current.knobProps.panelPadding).toEqual({ padding: "$4" });
   });
+});
 
-  it("compact:false inside a compact Surface stays compact and still steps space", () => {
-    const wrapper = ({ children }: { children: ReactNode }) =>
-      createElement(TestProviders, null, createElement(Surface, { density: "compact" }, children));
-    const { result } = renderHook(() => useResolvedKnobs({ compact: false }), { wrapper });
-    expect(result.current.knobProps.density).toBe("compact");
-    expect(result.current.knobProps.gap).toEqual({ gap: "$2" });
+describe("sizeTokenBelow", () => {
+  it("steps one whole key down, $true reading as $4, floored at $1", () => {
+    expect(sizeTokenBelow("$true")).toBe("$3");
+    expect(sizeTokenBelow("$4")).toBe("$3");
+    expect(sizeTokenBelow("$3")).toBe("$2");
+    expect(sizeTokenBelow("$5")).toBe("$4");
+    expect(sizeTokenBelow("$1")).toBe("$1");
+    expect(sizeTokenBelow("$3.5")).toBe("$3");
   });
 });