@multiplatform.one/theme 7.34.4 → 7.36.0

package/src/theme/resolveKnobs.ts

@@ -1,16 +1,22 @@
+import { motionFor } from "./motion";
 import { isTouchable, isWeb, isWebTouchable } from "@multiplatform.one/platform";
-import type { FontSizeTokens, TransitionProp } from "tamagui";
+import { getConfig } from "@tamagui/web";
+import type { FontSizeTokens } from "tamagui";
 // Importing the class constant also mounts the corner-shape stylesheet at
 // theme load (web only, idempotent) — see cornerSmoothing.ts.
 import { cornerSmoothClassName } from "./cornerSmoothing";
+import { headingCategoryFontKeys } from "./defaults/fonts";
 import {
   ensureFocusVisibleRing,
   STATE_LAYER_HOVER,
   STATE_LAYER_PRESS,
   withDefaultStateLayer,
 } from "./focusState";
+import { fontCategoryStacks } from "./fontCategoryStacks";
 import type { CornerSmoothing, Elevation, Knobs, PageTitleScale, StateKnobs } from "./knobs";
 import { pressTargetHitSlop } from "./layoutTokens";
+import { getActiveScaleTokens } from "./scale/activeScale";
+import { SIZE_KEYS, type SizeKey } from "./scale/scaleInputs";
 import type {
   ControlStateProps,
   DisabledRecipe,
@@ -25,45 +31,6 @@ import type {
 } from "./recipes";
 import { sizeRecipeForToken } from "./sizeRecipes";
 
-// ── Density (compact) stepping ────────────────────────────────
-
-/**
- * @deprecated Size is no longer coupled to density (LC-76). Compact density
- * steps space only. Kept exported because figmaTokens historically imported it.
- */
-export const compactSizeMap: Record<Knobs["size"], Knobs["size"]> = {
-  small: "small",
-  medium: "small",
-  large: "medium",
-};
-
-/** Step space down one level for compact density. */
-export const compactSpaceMap: Record<Knobs["space"], Knobs["space"]> = {
-  small: "small",
-  medium: "small",
-  large: "medium",
-};
-
-/**
- * Apply density mode to knobs before token resolution.
- *
- * - `density: "compact"` steps **space only** (`compactSpaceMap`). Size is an
- *   independent axis (LC-76) — compact must not shrink controls.
- * - `compactOverride` wins over the density knob when provided:
- *   `true` forces compact space stepping; `false` forces comfortable (no step).
- */
-export function applyDensity(knobs: Knobs, compactOverride?: boolean): Knobs {
-  const useCompact = compactOverride !== undefined ? compactOverride : knobs.density === "compact";
-  if (!useCompact) {
-    return knobs.density === "comfortable" ? knobs : { ...knobs, density: "comfortable" };
-  }
-  return {
-    ...knobs,
-    density: "compact",
-    space: compactSpaceMap[knobs.space],
-  };
-}
-
 // ── Knob-to-token mapping tables ──────────────────────────────
 
 export const borderRadiusMap = {
@@ -74,6 +41,14 @@ export const borderRadiusMap = {
   full: "$12",
 } as const;
 
+export const containerRadiusMap = {
+  none: "$0",
+  small: "$4",
+  medium: "$6",
+  large: "$8",
+  full: "$12",
+} as const;
+
 // 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.
@@ -108,16 +83,21 @@ const cornerSmoothingStyle: Record<CornerSmoothing, { className: string } | unde
   ? { round: undefined, smooth: { className: cornerSmoothClassName } }
   : { round: undefined, smooth: undefined };
 
-const panelPaddingMap = {
-  small: "$3",
-  medium: "$4",
-  large: "$6",
+// ── Spacing roles (SP-GAP, A9) ────────────────────────────────
+// Fixed `$space` keys. Their px come from the active scale, so a preset
+// that wants more or less room changes token values, never these keys.
+export const spacingRoles = {
+  gapSm: "$2",
+  gap: "$3",
+  gapLg: "$5",
+  panelPadding: "$4",
+  featurePadding: "$6",
 } as const;
 
 // Feature tier (SF-FEATURE, MPO-21 GL-59 ruling B): the Bento recipe's $10
-// radius and $6 inset at the default stops, one token per stop either side.
-// Uncapped by padding: the tightest pair (full 50 over small 24) still keeps
-// a child corner at the inset inside the arc (padding >= radius x 0.29).
+// radius over the `featurePadding` role ($6). Uncapped by padding: the
+// tightest pair (full 44 over 28) keeps a child corner at the inset inside
+// the arc (padding >= radius x 0.29).
 const featureRadiusMap = {
   none: "$0",
   small: "$9",
@@ -126,21 +106,11 @@ const featureRadiusMap = {
   full: "$12",
 } as const;
 
-const featurePaddingMap = {
-  small: "$5",
-  medium: "$6",
-  large: "$7",
-} as const;
-
 // ── Page-title step (D-11 hero-H1 dial) ───────────────────────
-// The one canonical definition of how big a page title is. On the heading
-// scale (1.4x Inter, defaults/fonts.ts) $8 = 32px and $10 = 64px, so
-// `moderate` lands in the page-title class while `display` keeps the
-// marketing hero step. Screens never pick a heading step by hand — they
-// spread `knobProps.pageTitle`, so one knob flip re-scales every title.
+// Default type 15: moderate is 40px; display is 52px.
 const pageTitleSizeMap: Record<PageTitleScale, FontSizeTokens> = {
-  moderate: "$8",
-  display: "$10",
+  moderate: "$10",
+  display: "$12",
 };
 
 /**
@@ -157,39 +127,39 @@ export function resolvePageTitleScale(scale: PageTitleScale): { size: FontSizeTo
 // ── Container radius cap (Axiom 1 CLIP) ──────────────────────
 // A padded container's effective radius must not exceed its own padding:
 // past that, the corner curve sweeps through the cell where children sit
-// (radius > padding clips child corners). Px values mirror the
-// @tamagui/themes tokens the maps above resolve to (radius $0/$2/$4/$6/$12
-// = 0/5/9/16/50; space $3/$4/$6 = 13/18/32) — resolveKnobs stays a pure
-// module, so the comparison happens on mirrored numbers, not live tokens.
-// The cap only bites at `full` (every space) and `large` under
-// `space=small`; default knobs are unchanged.
-
-const radiusPxMap: Record<Knobs["borderRadius"], number> = {
-  none: 0,
-  small: 5,
-  medium: 9,
-  large: 16,
-  full: 50,
+// (radius > padding clips child corners). Both px are read off the installed
+// scale: the knob's `$radius` key against the `panelPadding` role's `$space`.
+// Containers step two radius keys above controls; large and full hit the cap.
+
+const radiusKeyMap: Record<Knobs["borderRadius"], "0" | "4" | "6" | "8" | "12"> = {
+  none: "0",
+  small: "4",
+  medium: "6",
+  large: "8",
+  full: "12",
 };
 
-const panelPaddingPxMap: Record<Knobs["space"], number> = {
-  small: 13,
-  medium: 18,
-  large: 32,
-};
+/** The installed scale's `panelPadding` role in px. */
+export function panelPaddingPx(): number {
+  return getActiveScaleTokens().space[spacingRoles.panelPadding];
+}
 
 /**
  * Cap a container's radius at its own padding (Axiom 1 CLIP: "my children's
  * pixel clips first → cap at padding"). Returns the radius token untouched
  * while it fits, or the padding px number once the token would exceed it.
  */
-export function capContainerRadius(
-  borderRadius: Knobs["borderRadius"],
-  space: Knobs["space"],
-): string | number {
-  const radiusPx = radiusPxMap[borderRadius];
-  const paddingPx = panelPaddingPxMap[space];
-  return radiusPx > paddingPx ? paddingPx : borderRadiusMap[borderRadius];
+export function capContainerRadius(borderRadius: Knobs["borderRadius"]): string | number {
+  const radiusPx = getActiveScaleTokens().radius[radiusKeyMap[borderRadius]];
+  const paddingPx = panelPaddingPx();
+  return radiusPx > paddingPx ? paddingPx : containerRadiusMap[borderRadius];
+}
+
+export function capFieldRadius(borderRadius: Knobs["borderRadius"]): string | number {
+  const token = borderRadiusMap[borderRadius];
+  const radiusPx = getActiveScaleTokens().radius[token.slice(1) as "0" | "2" | "4" | "6" | "12"];
+  const paddingPx = panelPaddingPx();
+  return radiusPx > paddingPx ? paddingPx : token;
 }
 
 /**
@@ -208,93 +178,93 @@ export function radiusStopFromToken(token: unknown): Knobs["borderRadius"] | und
  * `StackedRow` is one row of a vertical stack: it also carries
  * `data-stack-position`, and only its outer corners take the cap.
  * `OwnInset` pads with a fixed token instead of panelPadding, so the audit
- * caps it at its measured padding and ignores the space stop.
+ * caps it at its measured padding.
  */
 export type CappedContainer = "PageSection" | "TextArea" | "StackedRow" | "OwnInset";
 
 export interface ContainerCapDeclaration {
   "data-constraint-container": CappedContainer;
   "data-radius-knob": Knobs["borderRadius"];
-  "data-space-knob": Knobs["space"];
 }
 
 /**
- * Declare a container that spreads `containerRadius`, with the knob stops it
+ * Declare a container that spreads `containerRadius`, with the knob stop it
  * resolved, so the constraint audit checks its painted corners against
- * `capContainerRadius` for those stops. The cap is a padding px value, not a
- * radius token, so an undeclared capped container reads off-scale at `full`.
- * Returns nothing when `radiusToken` is not a `borderRadiusMap` token or
- * `space` is not a space stop: a part whose radius did not come from the knob
+ * `capContainerRadius` for that stop on the page's scale, or `capFieldRadius`
+ * for TextArea's `fieldRadius`. The input is always the CONTROL token. The cap is a
+ * padding px value, not a radius token. Returns nothing when `radiusToken` is not a
+ * `borderRadiusMap` token: a part whose radius did not come from the knob
  * makes no claim.
  *
  * @example
- * <YStack {...knobProps.containerRadius} {...containerCapProps("PageSection", knobProps.borderRadius.borderRadius, knobProps.space)} />
+ * <YStack {...knobProps.containerRadius} {...containerCapProps("PageSection", knobProps.borderRadius.borderRadius)} />
  */
 export function containerCapProps(
   container: CappedContainer,
   radiusToken: unknown,
-  space: string,
 ): ContainerCapDeclaration | undefined {
   const radiusKnob = radiusStopFromToken(radiusToken);
-  if (!radiusKnob || !Object.hasOwn(panelPaddingPxMap, space)) return undefined;
+  if (!radiusKnob) return undefined;
   return {
     "data-constraint-container": container,
     "data-radius-knob": radiusKnob,
-    "data-space-knob": space as Knobs["space"],
   };
 }
 
-const gapMap = {
-  small: "$2",
-  medium: "$4",
-  large: "$5",
-} as const;
+const sizeKeys = new Set<string>(SIZE_KEYS);
 
-// gapLg stays one step above gapMap.
-const gapLgMap = {
-  small: "$3",
-  medium: "$5",
-  large: "$6",
-} as const;
+/** `sizeToken` when it is a `$size` key, else `$true`. */
+export function normalizeSizeToken(sizeToken: string | undefined): SizeKey {
+  return sizeToken !== undefined && sizeKeys.has(sizeToken) ? (sizeToken as SizeKey) : "$true";
+}
 
-const sizeTokenMap = {
-  small: "$3",
-  medium: "$4",
-  large: "$5",
-} as const;
+const nestedControlRatio = 32 / 44;
 
-/** Control-chrome type — one step below the matching sizeToken height. */
-const labelFontSizeMap = {
-  small: "$2",
-  medium: "$3",
-  large: "$4",
-} as const;
+/** Painted px of a nested hit-target (calendar days) at `sizeToken`: 32/44 of the token's `$size`. */
+export function nestedControlPx(sizeToken: string): number {
+  return Math.round(
+    getActiveScaleTokens().size[normalizeSizeToken(sizeToken)] * nestedControlRatio,
+  );
+}
 
 /**
- * Painted size for nested hit-targets (calendar days). Always below the
- * 44px floor; press is restored with hitSlop. Steps with `size` (compact
- * density steps space only — LC-76 — so nested chrome follows the size axis).
+ * The whole key one below a size key ($4 / $true -> $3, $3 -> $2,
+ * $3.5 -> $3, floor $1). Parts drawn one step under their control (tags,
+ * avatars) read it.
  */
-const nestedControlPxMap = {
-  small: 28,
-  medium: 32,
-  large: 36,
-} as const;
+export function sizeKeyBelow(sizeToken: string): `$${number}` {
+  const key = normalizeSizeToken(sizeToken);
+  const step = key === "$true" ? 4 : Number.parseFloat(key.slice(1));
+  return `$${Math.min(16, Math.max(1, Math.ceil(step) - 1))}`;
+}
+
+/** The body font key at the size key; half steps round up, and `$true` stays `$true`. */
+export function labelFontSizeFor(sizeToken: string): FontSizeTokens {
+  const key = normalizeSizeToken(sizeToken);
+  if (key === "$true") return "$true";
+  return `$${Math.min(16, Math.max(1, Math.ceil(Number.parseFloat(key.slice(1)))))}` as FontSizeTokens;
+}
 
 const headingFontMap = {
   "sans-serif": "$heading",
-  serif: "$serif",
-  mono: "$mono",
-  slab: "$slab",
-  rounded: "$rounded",
-  condensed: "$condensed",
-  cursive: "$cursive",
-  handwriting: "$handwriting",
-  pixel: "$pixel",
-  blackletter: "$blackletter",
-  geometric: "$geometric",
+  serif: `$${headingCategoryFontKeys.serif}`,
+  mono: `$${headingCategoryFontKeys.mono}`,
+  slab: `$${headingCategoryFontKeys.slab}`,
+  rounded: `$${headingCategoryFontKeys.rounded}`,
+  condensed: `$${headingCategoryFontKeys.condensed}`,
+  cursive: `$${headingCategoryFontKeys.cursive}`,
+  handwriting: `$${headingCategoryFontKeys.handwriting}`,
+  pixel: `$${headingCategoryFontKeys.pixel}`,
+  blackletter: `$${headingCategoryFontKeys.blackletter}`,
+  geometric: `$${headingCategoryFontKeys.geometric}`,
 } as const;
 
+export function getHeadingFontFamily(category: Knobs["headingFont"]): string {
+  const family = getConfig().fontsParsed[headingFontMap[category]]?.family;
+  const value = typeof family === "string" ? family : family?.val;
+  return typeof value === "string" ? value : fontCategoryStacks[category];
+}
+
 const bodyFontMap = {
   "sans-serif": "$body",
   serif: "$serif",
@@ -314,149 +284,66 @@ const fontWeightMap = {
   bold: "700",
 } as const;
 
-// Web keeps Tamagui size-token strings — Tamagui resolves them to boxShadow.
-// Native must emit NUMBERS: knobProps.elevation gets spread onto plain RN
-// Views by non-Tamagui consumers, and Android's RCTView `elevation` prop is a
-// Double — a token string kills the ReactHost with "java.lang.String cannot
-// 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.
+// Stops are `$size` keys; the shadow is Tamagui's getSizedElevation of that
+// key's px on the active scale. Native gets the px NUMBER: knobProps.elevation
+// is spread onto plain RN Views, and Android's RCTView `elevation` is a Double,
+// so a token string kills the ReactHost (SB-N-04).
 //
-// Controls are flat at the default `small` stop (MPO-96: the reference
-// measures no resting shadow on a button or a card), so `small` paints
-// nothing on the control map and only medium / large lift a control.
-// Overlay elevation is a DISTINCT ladder one step above the control map, so
-// a dialog over a scrim and a Button on the page never 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: undefined, medium: "$2", large: "$4" }
-  : { none: undefined, small: undefined, 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",
-};
-
-type ElevationKey = "$1" | "$2" | "$3" | "$4" | "$5";
-
-// Axiom 14 light source: y-offset:blur = 0.5. Metrics match the maps
-// InputParts / getElevationWrapperProps already shipped. `$3` and `$5` are
-// the overlay-only stops (MPO-99): the reference §8 popper and dialog
-// shadows. Native paints one shadow, so it takes the first web layer.
-const elevationShadowMetrics: Record<
-  ElevationKey,
-  { offsetY: number; radius: number; android: number }
-> = {
-  $1: { offsetY: 1, radius: 2, android: 2 },
-  $2: { offsetY: 3, radius: 6, android: 4 },
-  $3: { offsetY: 4, radius: 8, android: 6 },
-  $4: { offsetY: 10, radius: 20, android: 8 },
-  $5: { offsetY: 12, radius: 24, android: 12 },
-};
-
-const elevationKeyAlias: Record<string, ElevationKey> = {
-  $1: "$1",
-  $2: "$2",
-  $3: "$3",
-  $4: "$4",
-  $5: "$5",
-  "20": "$1",
-  "28": "$2",
-  "36": "$3",
-  "44": "$4",
-  "52": "$5",
-};
-
-const webShadowLight: Record<ElevationKey, 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)",
-  $3: "0 4px 8px rgba(0,0,0,0.10), 0 12px 32px rgba(0,0,0,0.08)",
-  $4: "0 10px 20px rgba(0,0,0,0.15), 0 3px 6px rgba(0,0,0,0.10)",
-  $5: "0 12px 24px rgba(0,0,0,0.12)",
+// Controls are flat at the default `small` stop (MPO-96). Overlays climb a
+// distinct ladder above the control map so a dialog over a scrim and a Button
+// on the page never read as the same distance (DG-OVL-01 / E-OVERLAY). The
+// overlay default is `$4`, the control height: on the 40px default scale `$3`
+// (32px) casts a 22px band, under the 24px that lifts a dialog off its scrim.
+export const elevationMap: Record<Elevation, SizeKey | undefined> = {
+  none: undefined,
+  small: undefined,
+  medium: "$2",
+  large: "$4",
 };
 
-// LC-85: dark keeps each stop's geometry and inverts the hue.
-const webShadowDark: Record<ElevationKey, 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)",
-  $3: "0 4px 8px rgba(255,255,255,0.10), 0 12px 32px rgba(255,255,255,0.08)",
-  $4: "0 10px 20px rgba(255,255,255,0.12), 0 3px 6px rgba(255,255,255,0.08)",
-  $5: "0 12px 24px rgba(255,255,255,0.12)",
+export const overlayElevationMap: Record<Elevation, SizeKey | undefined> = {
+  none: undefined,
+  small: "$4",
+  medium: "$4.5",
+  large: "$5",
 };
 
-const shadowOpacityLight: Record<ElevationKey, number> = {
-  $1: 0.12,
-  $2: 0.15,
-  $3: 0.1,
-  $4: 0.15,
-  $5: 0.12,
-};
+export type ColorScheme = "light" | "dark";
 
-const shadowOpacityDark: Record<ElevationKey, number> = {
-  $1: 0.08,
-  $2: 0.1,
-  $3: 0.1,
-  $4: 0.12,
-  $5: 0.12,
-};
+export function sizedElevation(px: number): { offsetY: number; radius: number; android: number } {
+  const offsetY = Math.round(px / 4 + 1);
+  return { offsetY, radius: Math.round(px / 2 + 2), android: 2 * offsetY };
+}
 
-function elevationTokenKey(token: string | number | undefined): ElevationKey | undefined {
-  if (token == null) return undefined;
-  return elevationKeyAlias[String(token)];
+function platformElevation(key: SizeKey | undefined): string | number | undefined {
+  return key && (isWeb ? key : getActiveScaleTokens().size[key]);
 }
 
-function elevationPaint(
-  token: string | number | undefined,
-  scheme: ColorScheme,
-): ElevationPaintProps {
-  const key = elevationTokenKey(token);
+function elevationPaint(key: SizeKey | undefined): ElevationPaintProps {
   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 ? shadowOpacityDark[key] : shadowOpacityLight[key],
-    shadowRadius: metrics.radius,
+  const { offsetY, radius } = sizedElevation(getActiveScaleTokens().size[key]);
+  return {
+    shadowColor: "$shadowColor",
+    shadowOffset: { width: 0, height: offsetY },
+    shadowOpacity: 1,
+    shadowRadius: radius,
+    ...(isWeb ? { style: { boxShadow: `0px ${offsetY}px ${radius}px var(--shadowColor)` } } : {}),
   };
-  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);
+function elevationChromeFor(key: SizeKey | undefined): ElevationChromeProps {
   if (!key) return {};
   return {
-    ...elevationPaint(token, scheme),
-    elevation: elevationShadowMetrics[key].android,
+    ...elevationPaint(key),
+    elevation: sizedElevation(getActiveScaleTokens().size[key]).android,
   };
 }
 
+// v5's surface2 template steps: fill and edge two palette steps above the
+// base `$background`/`$borderColor` (color2/color4), one above Card's surface1.
+// The fill alone would land on the base edge step and erase the border.
+const surface2 = { fill: "$color4", edge: "$color6" } as const;
+
 // 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).
@@ -527,10 +414,7 @@ function resolveDisabled(disabledStyle: Knobs["disabledStyle"]): DisabledRecipe
 
 // ── State style resolver ──────────────────────────────────────
 
-function resolveStateKnobs(
-  state: StateKnobs,
-  scheme: ColorScheme,
-): {
+function resolveStateKnobs(state: StateKnobs): {
   control: ControlStateProps;
   text: TextStateProps;
   elevation: ElevationStateProps;
@@ -548,16 +432,10 @@ function resolveStateKnobs(
   if (state.borderRadius !== undefined) {
     control.borderRadius = borderRadiusMap[state.borderRadius];
   }
-  if (state.space !== undefined) {
-    control.padding = gapMap[state.space];
-  }
   if (state.elevation !== undefined) {
     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];
-    }
+    elevation.elevation = platformElevation(token);
+    Object.assign(elevation, elevationPaint(token));
   }
   if (state.textAccent !== undefined) {
     text.color = textAccentColorMap[state.textAccent];
@@ -576,28 +454,49 @@ function resolveStateKnobs(
 
 // ── Resolver ──────────────────────────────────────────────────
 
+/** Vertical inset of a top bar; with the default control height it lands the bar at 52. */
+const barPaddingToken = "$2";
+/**
+ * A content card on a painted parent sits one ramp step off it, so the box
+ * reads without a shadow (nested surfaces never re-elevate).
+ */
+export const paintedCardFill = "$color2";
+
+/** What the subtree supplies beyond knobs: the pointer surface and the control size token. */
+export interface ResolveKnobsEnvironment {
+  touch?: boolean;
+  /** Tamagui size key the controls render at. Default `$true`. */
+  sizeToken?: string;
+  /**
+   * An ancestor already paints a surface box: `elevatedSurface` goes border
+   * only (no second shadow) and `cardSurface` steps one fill off the parent.
+   */
+  painted?: boolean;
+}
+
 export function resolveKnobs(
   knobs: Knobs,
   override?: KnobPropsOverride,
   scheme: ColorScheme = "light",
-  environment?: { touch?: boolean },
+  environment?: ResolveKnobsEnvironment,
 ): ResolvedKnobs {
   const radiusToken = borderRadiusMap[knobs.borderRadius];
   const nestedRadiusToken = nestedRadiusMap[knobs.borderRadius];
-  const sizeToken = sizeTokenMap[knobs.size];
-  const nestedPx = nestedControlPxMap[knobs.size];
+  const sizeToken = normalizeSizeToken(environment?.sizeToken);
+  const painted = environment?.painted ?? false;
+  const nestedPx = nestedControlPx(sizeToken);
   const nestedHitSlop = pressTargetHitSlop(nestedPx);
-  const sizeRecipe = sizeRecipeForToken(sizeToken, {
-    touch: environment?.touch ?? (isTouchable || isWebTouchable),
-    family: knobs.density === "compact" ? "controlCompact" : "control",
-  });
-  const paddingToken = panelPaddingMap[knobs.space];
-  const gapToken = gapMap[knobs.space];
+  const touch = environment?.touch ?? (isTouchable || isWebTouchable);
+  const sizeRecipe = sizeRecipeForToken(sizeToken, { touch });
+  const menuRowRecipe = sizeRecipeForToken(sizeToken, { touch, family: "menuRow" });
+  const tabRecipe = sizeRecipeForToken(sizeToken, { touch, family: "tab" });
+  const scaleTokens = getActiveScaleTokens();
+  const paddingToken = spacingRoles.panelPadding;
   const fontWeightValue = fontWeightMap[knobs.fontWeight];
   const bodyFontValue = bodyFontMap[knobs.bodyFont] ?? "$body";
-  const transition = knobs.animation === "none" ? undefined : (knobs.animation as TransitionProp);
+  const motion = motionFor(knobs.animation);
 
-  const containerRadiusValue = capContainerRadius(knobs.borderRadius, knobs.space);
+  const containerRadiusValue = capContainerRadius(knobs.borderRadius);
 
   // Corner smoothing rides every radius-bearing fragment so consumers need
   // zero edits (KNOB-TOTALITY, LC-18). Identity guard (Axiom 3 NULL +
@@ -624,29 +523,18 @@ export function resolveKnobs(
       : 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 overlayPaintProps = elevationPaint(overlayElevationToken);
+  const elevationChrome = elevationChromeFor(elevationToken);
   const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
   // 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 inputBackground = outlined ? "transparent" : "$background";
+
+  const hover = resolveStateKnobs(knobs.hover);
+  const press = resolveStateKnobs(knobs.press);
+  const focus = resolveStateKnobs(knobs.focus);
+  const focusVisible = resolveStateKnobs(knobs.focusVisible);
 
   const nonEmpty = <T extends object>(obj: T): T | undefined =>
     Object.keys(obj).length > 0 ? obj : undefined;
@@ -695,9 +583,11 @@ export function resolveKnobs(
     // spread this after their radius-bearing fragment. Non-container parts
     // keep the uncapped `borderRadius` fragment.
     containerRadius: { borderRadius: containerRadiusValue, ...containerSmoothing },
-    elevation: elevationToken,
-    overlayElevation: overlayElevationToken,
+    fieldRadius: { borderRadius: capFieldRadius(knobs.borderRadius), ...containerSmoothing },
+    elevation: platformElevation(elevationToken),
+    overlayElevation: platformElevation(overlayElevationToken),
     elevationChrome,
+    thumbShadow: elevationChromeFor("$0.5"),
     scheme,
     surface: {
       backgroundColor: "$background",
@@ -705,24 +595,33 @@ export function resolveKnobs(
       borderWidth: borderWidthValue,
     },
     cardSurface: {
-      backgroundColor: overlayFill,
+      backgroundColor: painted ? paintedCardFill : "$background",
       borderRadius: containerRadiusValue,
       padding: paddingToken,
       ...containerSmoothing,
     },
-    elevatedSurface: {
-      backgroundColor: overlayFill,
-      borderColor: "$borderColor",
-      borderWidth: borderWidthValue,
-      borderRadius: radiusToken,
-      elevation: overlayElevationToken,
-      ...overlayPaintProps,
-      ...scaleSmoothing,
-    },
+    elevatedSurface: painted
+      ? {
+          backgroundColor: "$background",
+          borderColor: "$borderColor",
+          borderWidth: Math.max(borderWidthValue, borderWidthMap.small),
+          borderRadius: radiusToken,
+          elevation: undefined,
+          ...scaleSmoothing,
+        }
+      : {
+          backgroundColor: scheme === "dark" ? surface2.fill : "$background",
+          borderColor: scheme === "dark" ? surface2.edge : "$borderColor",
+          borderWidth: borderWidthValue,
+          borderRadius: radiusToken,
+          elevation: platformElevation(overlayElevationToken),
+          ...overlayPaintProps,
+          ...scaleSmoothing,
+        },
     featureSurface: {
       backgroundColor: "$background",
       borderRadius: featureRadiusMap[knobs.borderRadius],
-      padding: featurePaddingMap[knobs.space],
+      padding: spacingRoles.featurePadding,
       // Bento marketing/auth card shadow: ~0px 9px 12px rgba(0,0,0,0.02) —
       // softer/wider than any elevationMap token, so explicit shadow props.
       shadowColor: "rgba(0,0,0,0.02)",
@@ -733,13 +632,14 @@ export function resolveKnobs(
     },
     inputSurface: { borderWidth: borderWidthValue },
     panelPadding: { padding: paddingToken },
-    gap: { gap: gapToken },
-    gapLg: { gap: gapLgMap[knobs.space] },
+    gapSm: { gap: spacingRoles.gapSm },
+    gap: { gap: spacingRoles.gap },
+    gapLg: { gap: spacingRoles.gapLg },
     sizeToken,
     label: {
-      fontSize: labelFontSizeMap[knobs.size],
+      fontSize: labelFontSizeFor(sizeToken),
       fontFamily: bodyFontValue,
-      fontWeight: fontWeightValue,
+      ...(knobs.fontWeight === "bold" ? { fontWeight: "700" } : {}),
     },
     nestedControl: {
       px: nestedPx,
@@ -758,25 +658,50 @@ export function resolveKnobs(
     },
     controlType: { fontSize: sizeRecipe.fontSize },
     controlIcon: { width: sizeRecipe.iconSize, height: sizeRecipe.iconSize },
+    menuRow: {
+      minHeight: menuRowRecipe.height,
+      paddingHorizontal: menuRowRecipe.paddingHorizontal,
+      gap: menuRowRecipe.gap,
+    },
+    menuRowType: { fontSize: menuRowRecipe.fontSize },
+    tab: {
+      height: tabRecipe.height,
+      paddingHorizontal: tabRecipe.paddingHorizontal,
+      gap: tabRecipe.gap,
+    },
+    tabType: { fontSize: tabRecipe.fontSize },
+    tabHitSlop: pressTargetHitSlop(tabRecipe.height),
+    bar: {
+      frame: {
+        paddingVertical: barPaddingToken,
+        paddingHorizontal: paddingToken,
+        minHeight: scaleTokens.size.$true + 2 * scaleTokens.space[barPaddingToken],
+      },
+      sizeToken: "$3",
+    },
     heading: {
       fontFamily: headingFontMap[knobs.headingFont],
-      fontWeight: fontWeightValue,
+      ...(knobs.fontWeight === "bold" ? { fontWeight: "700" } : {}),
     },
     pageTitle: resolvePageTitleScale(knobs.pageTitleScale ?? "moderate"),
     body: {
       fontFamily: bodyFontValue,
       fontWeight: fontWeightValue,
     },
+    typography: {
+      mutedMono: { fontFamily: "$mono", color: textAccentColorMap.low },
+      tabular: isWeb
+        ? { style: { fontVariantNumeric: "tabular-nums" } }
+        : { fontVariant: ["tabular-nums"] },
+    },
     textWeight: { fontWeight: fontWeightValue },
-    transition,
+    motion,
+    transition: motion.control.transition,
     outlined,
     pointy: knobs.borderRadius === "none",
     textAccent: knobs.textAccent,
     textAccentColor,
     inputBackground,
-    space: knobs.space,
-    size: knobs.size,
-    density: knobs.density,
     // House decisions — behavioral pass-through (no token mapping).
     fieldLabelPlacement: knobs.fieldLabelPlacement,
     requiredMarking: knobs.requiredMarking,