@multiplatform.one/theme 7.34.4 → 7.36.0

package/src/theme/devtools/ThemeDevtoolsPanel.tsx

@@ -5,10 +5,10 @@
  *
  * Controls:
  *  - Color scheme (system / light / dark) via @vxrn/color-scheme
- *  - Preset picker (using registered presets)
+ *  - Preset picker (using registered presets), each listed with its token
+ *    scale (control / type px): size and spacing come from the preset's scale
  *  - All knobs: fillStyle, borderRadius, cornerSmoothing, borderWidth,
- *    elevation, space, size, density, textAccent, headingFont, bodyFont,
- *    fontWeight, animation,
+ *    elevation, textAccent, headingFont, bodyFont, fontWeight, animation,
  *    plus house decisions (fieldLabelPlacement, requiredMarking, tableZebra,
  *    bulkBarPlacement, selectAllScope, timestampStyle, disabledStyle,
  *    formAutofocus)
@@ -55,9 +55,6 @@ import {
   CornerSmoothing,
   BorderWidth,
   Elevation,
-  Space,
-  Size,
-  Density,
   TextAccent,
   HeadingFont,
   BodyFont,
@@ -73,14 +70,12 @@ import {
   interactionStates,
 } from "../knobs";
 import { getPresetNames, getPreset } from "../shared";
+import { defaultScaleInputs } from "../scale/scaleInputs";
 import { extractAnimationNames } from "./animationOptions";
 import { ColorLineVisualizer } from "./ColorLineVisualizer";
 import { buildSnapshot } from "./buildSnapshot";
 import {
   fillIcon as _fillIcon,
-  spaceIcon as _spaceIcon,
-  sizeIcon as _sizeIcon,
-  densityIcon as _densityIcon,
   borderRadiusIcon as _borderRadiusIcon,
   cornerSmoothingIcon as _cornerSmoothingIcon,
   borderWidthIcon as _borderWidthIcon,
@@ -128,9 +123,6 @@ const knobKeys: (keyof Knobs)[] = [
   "cornerSmoothing",
   "borderWidth",
   "elevation",
-  "space",
-  "size",
-  "density",
   "textAccent",
   "headingFont",
   "bodyFont",
@@ -152,7 +144,6 @@ const stateKnobKeys: (keyof Knobs)[] = [
   "borderRadius",
   "borderWidth",
   "elevation",
-  "space",
   "textAccent",
   "headingFont",
   "bodyFont",
@@ -170,8 +161,6 @@ const designProfiles: Record<string, DesignProfile> = {
     borderRadius: "small",
     borderWidth: "medium",
     elevation: "none",
-    space: "medium",
-    size: "medium",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
@@ -184,8 +173,6 @@ const designProfiles: Record<string, DesignProfile> = {
     borderRadius: "large",
     borderWidth: "none",
     elevation: "small",
-    space: "medium",
-    size: "medium",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
@@ -199,8 +186,6 @@ const designProfiles: Record<string, DesignProfile> = {
     borderRadius: "small",
     borderWidth: "small",
     elevation: "none",
-    space: "medium",
-    size: "medium",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
@@ -213,8 +198,6 @@ const designProfiles: Record<string, DesignProfile> = {
     borderRadius: "small",
     borderWidth: "small",
     elevation: "small",
-    space: "medium",
-    size: "medium",
     textAccent: "high",
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
@@ -231,6 +214,15 @@ const profileNames = ["", ...Object.keys(designProfiles)] as const;
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** A preset picker option with the token scale it renders on (control / type px). */
+function formatPresetOption(name: string): string {
+  if (name === "") return "custom";
+  const scale = getPreset(name)?.scale;
+  const control = scale?.control ?? defaultScaleInputs.control;
+  const type = scale?.type ?? defaultScaleInputs.type;
+  return `${name} · ${control}/${type}`;
+}
+
 type SchemeHook = {
   setting: "system" | "light" | "dark";
   value: "light" | "dark";
@@ -705,18 +697,6 @@ function fillIcon(v: string, active: boolean, dark: boolean): ReactNode {
   return _fillIcon(v, ic(active, dark));
 }
 
-function spaceIcon(v: string, active: boolean, dark: boolean): ReactNode {
-  return _spaceIcon(v, ic(active, dark));
-}
-
-function sizeIcon(v: string, active: boolean, dark: boolean): ReactNode {
-  return _sizeIcon(v, ic(active, dark));
-}
-
-function densityIcon(v: string, active: boolean, dark: boolean): ReactNode {
-  return _densityIcon(v, ic(active, dark));
-}
-
 function borderRadiusIcon(v: string, active: boolean, dark: boolean): ReactNode {
   return _borderRadiusIcon(v, ic(active, dark));
 }
@@ -1134,8 +1114,6 @@ export function ThemeDevtoolsPanel({
       borderRadius: Object.values(BorderRadius),
       borderWidth: Object.values(BorderWidth),
       elevation: Object.values(Elevation),
-      space: Object.values(Space),
-      size: Object.values(Size),
       textAccent: Object.values(TextAccent),
       headingFont: Object.values(HeadingFont),
       bodyFont: Object.values(BodyFont),
@@ -1155,7 +1133,6 @@ export function ThemeDevtoolsPanel({
         borderRadius: Object.values(BorderRadius),
         borderWidth: Object.values(BorderWidth),
         elevation: Object.values(Elevation),
-        space: Object.values(Space),
         textAccent: Object.values(TextAccent),
         headingFont: Object.values(HeadingFont),
         bodyFont: Object.values(BodyFont),
@@ -1353,7 +1330,7 @@ export function ThemeDevtoolsPanel({
             options={presetOptions}
             value={activePresetName ?? ""}
             onChange={(v) => handlePresetChange(v)}
-            format={(v) => (v === "" ? "custom" : String(v))}
+            format={formatPresetOption}
             styles={styles}
           />
         )}
@@ -1406,46 +1383,6 @@ export function ThemeDevtoolsPanel({
         >
           {stateRows("fillStyle", Object.values(FillStyle), fillIcon)}
         </IconGroup>
-        <IconGroup
-          label="Size"
-          options={Object.values(Size)}
-          value={getOverride("size")}
-          onChange={(v) => set("size", v)}
-          icon={sizeIcon}
-          styles={styles}
-          isDark={isDark}
-          pinned={pinnedKnobs.has("size")}
-          onTogglePin={() => togglePin("size")}
-          onUnset={() => unset("size")}
-        />
-        <IconGroup
-          label="Space"
-          options={Object.values(Space)}
-          value={getOverride("space")}
-          onChange={(v) => set("space", v)}
-          icon={spaceIcon}
-          styles={styles}
-          isDark={isDark}
-          pinned={pinnedKnobs.has("space")}
-          onTogglePin={() => togglePin("space")}
-          expanded={expandedKnobs.has("space")}
-          onToggleExpand={() => toggleExpand("space")}
-          onUnset={() => unset("space")}
-        >
-          {stateRows("space", Object.values(Space), spaceIcon)}
-        </IconGroup>
-        <IconGroup
-          label="Density"
-          options={Object.values(Density)}
-          value={getOverride("density")}
-          onChange={(v) => set("density", v)}
-          icon={densityIcon}
-          styles={styles}
-          isDark={isDark}
-          pinned={pinnedKnobs.has("density")}
-          onTogglePin={() => togglePin("density")}
-          onUnset={() => unset("density")}
-        />
         <IconGroup
           label="Radius"
           options={Object.values(BorderRadius)}

package/src/theme/devtools/animationOptions.spec.ts

@@ -1,44 +1,30 @@
 import { describe, expect, it } from "vitest";
-import { animationNames, animations } from "../animations/css";
+import { motionStops, animations } from "../animations/css";
 import { extractAnimationNames } from "./animationOptions";
 
-describe("extractAnimationNames (MPO-447)", () => {
-  it("lists the registered animations of a createTamagui config, not the driver's API", () => {
-    const names = extractAnimationNames({ animations });
-    expect(names).toEqual([...animationNames]);
-    for (const member of [
-      "usePresence",
-      "ResetPresence",
-      "inputStyle",
-      "outputStyle",
-      "useAnimatedNumber",
-      "useAnimations",
-    ]) {
-      expect(names).not.toContain(member);
-    }
+describe("extractAnimationNames", () => {
+  it("offers only ordered motion stops on the house driver", () => {
+    expect(extractAnimationNames({ animations })).toEqual([...motionStops]);
   });
-
-  it("offers exactly the house names on the house driver", () => {
-    expect(extractAnimationNames({ animations })).toEqual([
-      "bouncy",
-      "lazy",
-      "slow",
-      "medium",
-      "quick",
-      "tooltip",
-      "snappy",
-      "gentle",
-    ]);
-  });
-
-  it("reads an app's own driver names when it registers different ones", () => {
-    const driver = { ...animations, animations: { fast: "ease-in 50ms", calm: "ease-in 900ms" } };
-    expect(extractAnimationNames({ animations: driver })).toEqual(["fast", "calm"]);
+  it("filters custom drivers to registered knob stops in duration order", () => {
+    expect(
+      extractAnimationNames({
+        animations: {
+          animations: {
+            slow: "450ms",
+            quick: "150ms",
+            quickest: "80ms",
+            tooltip: "450ms",
+            "100ms": "100ms",
+            foreign: "1s",
+          },
+        },
+      }),
+    ).toEqual(["quickest", "quick", "slow"]);
   });
-
-  it("falls back to the house names without a config or without named animations", () => {
-    expect(extractAnimationNames(undefined)).toEqual([...animationNames]);
-    expect(extractAnimationNames({})).toEqual([...animationNames]);
-    expect(extractAnimationNames({ animations: { animations: {} } })).toEqual([...animationNames]);
+  it("returns no stops for an empty driver, and defaults when no driver is available", () => {
+    expect(extractAnimationNames({ animations: { animations: {} } })).toEqual([]);
+    expect(extractAnimationNames(undefined)).toEqual([...motionStops]);
+    expect(extractAnimationNames({})).toEqual([...motionStops]);
   });
 });

package/src/theme/devtools/animationOptions.ts

@@ -1,4 +1,4 @@
-import { animationNames } from "../animations/index";
+import { motionStops } from "../animations/css";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -14,9 +14,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export function extractAnimationNames(tamaguiConfig: unknown): string[] {
   const driver = isRecord(tamaguiConfig) ? tamaguiConfig.animations : undefined;
   const named = isRecord(driver) ? driver.animations : undefined;
-  if (isRecord(named)) {
-    const keys = Object.keys(named);
-    if (keys.length > 0) return keys;
-  }
-  return [...animationNames];
+  return isRecord(named)
+    ? motionStops.filter((stop) => Object.hasOwn(named, stop))
+    : [...motionStops];
 }

package/src/theme/devtools/buildSnapshot.ts

@@ -6,9 +6,6 @@ const knobKeys = [
   "cornerSmoothing",
   "borderWidth",
   "elevation",
-  "space",
-  "size",
-  "density",
   "textAccent",
   "headingFont",
   "bodyFont",

package/src/theme/devtools/knobIcons.tsx

@@ -18,29 +18,6 @@ export function fillIcon(value: string, color: string): ReactNode {
   return <div style={{ width: 14, height: 14, border: `1.5px solid ${color}`, borderRadius: 2 }} />;
 }
 
-export function spaceIcon(value: string, color: string): ReactNode {
-  const size = ({ small: 8, medium: 12, large: 16 } as Record<string, number>)[value] ?? 12;
-  return <div style={{ width: size, height: size, background: color, borderRadius: 2 }} />;
-}
-
-export function sizeIcon(value: string, color: string): ReactNode {
-  const height = ({ small: 8, medium: 11, large: 14 } as Record<string, number>)[value] ?? 11;
-  return <div style={{ width: 4, height: height, background: color, borderRadius: 1 }} />;
-}
-
-export function densityIcon(value: string, color: string): ReactNode {
-  // Comfortable = taller stack; compact = compressed stack.
-  const gap = value === "compact" ? 1 : 2;
-  const barH = value === "compact" ? 3 : 4;
-  return (
-    <div style={{ display: "flex", flexDirection: "column", gap, width: 14 }}>
-      <div style={{ height: barH, background: color, borderRadius: 1 }} />
-      <div style={{ height: barH, background: color, borderRadius: 1 }} />
-      <div style={{ height: barH, background: color, borderRadius: 1 }} />
-    </div>
-  );
-}
-
 export function borderRadiusIcon(value: string, color: string): ReactNode {
   const radius =
     ({ none: 0, small: 2, medium: 4, large: 7, full: 10 } as Record<string, number>)[value] ?? 0;
@@ -350,7 +327,10 @@ export function formAutofocusIcon(value: string, color: string): ReactNode {
         height: 14,
         border: `1.5px solid ${color}`,
         borderRadius: 2,
-        boxShadow: value === "on" ? `0 0 0 2px ${color}` : undefined,
+        outlineWidth: value === "on" ? 2 : 0,
+        outlineStyle: "solid",
+        outlineColor: color,
+        outlineOffset: 0,
         opacity: value === "on" ? 1 : 0.45,
       }}
     />

package/src/theme/focusState.spec.ts

@@ -142,36 +142,15 @@ describe("$outlineColor token contrast (DF-03 / DG-A11Y-01)", () => {
     }
   }
 
-  it("the retired flat inset failed the floor over the solid intent fills (why offset is 0)", () => {
-    // The failures that forced the flip (MPO-41 / MPO-19 X7): a −2 band paints
-    // INSIDE the control, so it had to contrast against the solid intent fill.
-    //
-    // Provenance, because the two numbers are easy to conflate. The headline
-    // figures — light accent 1.27:1, light error 1.17:1, dark error 1.31:1 —
-    // are RENDERED measurements off the action-and-feedback board at DPR 2,
-    // ring node against the Button's painted background. This test computes a
-    // DIFFERENT pair: the base `outlineColor` against the intent sub-theme's
-    // `color9` ink step (1.67 / 1.55 / 1.44 in this build). Same verdict, same
-    // reason, different surfaces — the board's error fills (#ce2c31 / #ff9794)
-    // are not in these default sub-theme ramps at all, so the fill side is the
-    // board's to own and not this package's.
-    //
-    // What this assertion IS: no sub-theme ink step the inset band could land
-    // on clears the floor, which keeps the offset-0 geometry load-bearing. If
-    // the ramps ever lighten past 3:1 this test goes stale, not wrong.
-    for (const [scheme, intent] of [
-      ["light", "accent"],
-      ["light", "error"],
-      ["dark", "error"],
-    ] as const) {
-      const ring = normalizeToHex(themes[scheme].outlineColor);
-      const fill = normalizeToHex(themes[`${scheme}_${intent}`].color9);
-      expect(ring).toBeTruthy();
-      expect(fill).toBeTruthy();
-      expect(contrastRatio(relativeLuminance(ring!), relativeLuminance(fill!))).toBeLessThan(
-        FOCUS_RING_MIN_CONTRAST,
-      );
-    }
+  it("an inset ring cannot guarantee contrast over every solid intent fill", () => {
+    const ratios = (["light", "dark"] as const).flatMap((scheme) =>
+      ["accent", "error", "success", "warning"].map((intent) => {
+        const ring = normalizeToHex(themes[scheme].outlineColor)!;
+        const fill = normalizeToHex(themes[`${scheme}_${intent}_Button`].background)!;
+        return contrastRatio(relativeLuminance(ring), relativeLuminance(fill));
+      }),
+    );
+    expect(ratios.some((ratio) => ratio < FOCUS_RING_MIN_CONTRAST)).toBe(true);
   });
 });
 

package/src/theme/index.ts

@@ -22,12 +22,17 @@ export * from "./layoutTokens";
 export * from "./Preset";
 export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
 export * from "./PresetContext";
+export * from "./presetPreview";
 export * from "./presets";
+export * from "./presetStore";
+export * from "./presetUserSync";
 export * from "./radiusClass";
 export * from "./radiusClassTable.generated";
 export * from "./readableColor";
 export * from "./recipes";
 export * from "./resolveKnobs";
+export * from "./schemeStore";
+export * from "./scale/index";
 export * from "./shared";
 export * from "./themeValue";
 export * from "./sizeRecipes";
@@ -40,4 +45,16 @@ export * from "./theme";
 export * from "./Tint";
 export * from "./useResolvedKnobs";
 export * from "./useTheme";
+export * from "./usePresetSwitch";
+export * from "./useSchemePreference";
 export * from "./useTouchSurface";
+export * from "./overlaySurfaces";
+
+export * from "./motion";
+export {
+  animationConfig as cssAnimationConfig,
+  animationDurations,
+  motionStops,
+  type MotionStop,
+} from "./animations/css";
+export { animationConfig as nativeAnimationConfig } from "./animations/reactNative";

package/src/theme/intentFill.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import { createThemesBuilder } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+
+const themes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+
+const hex = (raw: string) => {
+  const value = normalizeToHex(raw);
+  if (!value) throw new Error(`not an opaque colour: ${raw}`);
+  return value;
+};
+const luminance = (raw: string) => relativeLuminance(hex(raw));
+const ratio = (a: string, b: string) => contrastRatio(luminance(a), luminance(b));
+const lightness = (raw: string) => {
+  const value = hex(raw);
+  const channels = [1, 3, 5].map((offset) => Number.parseInt(value.slice(offset, offset + 2), 16));
+  return ((Math.max(...channels) + Math.min(...channels)) / (2 * 255)) * 100;
+};
+
+describe("FZ-7158 WP-b5: semantic Button fills hold their pale ink", () => {
+  for (const scheme of ["light", "dark"] as const) {
+    for (const intent of ["error", "warning", "success"] as const) {
+      it(`${scheme}_${intent}_Button darkens from its resting fill in both interaction states`, () => {
+        const theme = themes[`${scheme}_${intent}_Button`];
+        expect(lightness(theme.background)).toBeLessThan(60);
+        expect(luminance(theme.color)).toBeGreaterThan(0.5);
+        for (const fill of [theme.background, theme.backgroundHover, theme.backgroundPress]) {
+          expect(ratio(theme.color, fill)).toBeGreaterThanOrEqual(4.5);
+        }
+        expect(lightness(theme.backgroundHover)).toBeLessThan(lightness(theme.background));
+        expect(lightness(theme.backgroundPress)).toBeLessThan(lightness(theme.backgroundHover));
+      });
+    }
+  }
+});

package/src/theme/knobs.ts

@@ -55,27 +55,6 @@ export const Elevation = {
 } as const;
 export type Elevation = (typeof Elevation)[keyof typeof Elevation];
 
-export const Space = {
-  Small: "small",
-  Medium: "medium",
-  Large: "large",
-} as const;
-export type Space = (typeof Space)[keyof typeof Space];
-
-export const Size = {
-  Small: "small",
-  Medium: "medium",
-  Large: "large",
-} as const;
-export type Size = (typeof Size)[keyof typeof Size];
-
-/** Global density mode — compact steps space down one level; size is independent. */
-export const Density = {
-  Comfortable: "comfortable",
-  Compact: "compact",
-} as const;
-export type Density = (typeof Density)[keyof typeof Density];
-
 // ── House decisions (design-guidelines.md) ─────────────────
 // Behavioral knobs with recommended defaults — not hard constraints.
 
@@ -191,17 +170,11 @@ export const FontWeight = {
 export type FontWeight = (typeof FontWeight)[keyof typeof FontWeight];
 
 /**
- * Page-title type step (D-11 hero-H1 dial, owner ruling 2026-08-12).
- *
- * `moderate` ($8 = 32px) is the product default: a page title is wayfinding,
- * not content, so it does not spend the display scale's emphasis budget
- * (Axiom 10) — and the 64px step is the direct amplifier of the DF-02 title
- * clip. `display` ($10 = 64px) is the deliberate marketing/hero opt-in,
- * reached through the `hero` preset or an explicit knob override; it is never
- * the ambient default.
- *
- * Two values, not a token dial: a free size invites per-screen drift
- * (Axiom 5), and the semantic level stays `headingLevel`'s job either way.
+ * Page-title type step (D-11 dial). `moderate` ($10, 40 px at type 15) is the
+ * product default: a page title is wayfinding, not content (Axiom 10).
+ * `display` ($12, 52 px) is the hero opt-in, through `heroPreset` or an
+ * explicit override. Two values, not a free size: a free size invites
+ * per-screen drift (Axiom 5), and the semantic level stays `headingLevel`'s.
  */
 export const PageTitleScale = {
   Moderate: "moderate",
@@ -211,9 +184,16 @@ export type PageTitleScale = (typeof PageTitleScale)[keyof typeof PageTitleScale
 
 // ── Animation ──────────────────────────────────────────────
 
-import type { AnimationName } from "./animations/index";
+import { motionStops, type MotionStop } from "./motionStops";
+
+export type Animation = "none" | MotionStop;
 
-export type Animation = "none" | AnimationName;
+export function normalizeAnimationKnob(value: unknown): Animation | undefined {
+  if (value === "none" || motionStops.includes(value as MotionStop)) return value as Animation;
+  if (value === "tooltip" || value === "gentle") return "slow";
+  if (value === "snappy") return "quickest";
+  return undefined;
+}
 
 // ── Interaction state overrides ────────────────────────────
 // Structural knobs that can vary per interaction state.
@@ -223,7 +203,6 @@ export interface StateKnobs {
   borderRadius?: BorderRadius;
   borderWidth?: BorderWidth;
   elevation?: Elevation;
-  space?: Space;
   textAccent?: TextAccent;
   headingFont?: HeadingFont;
   bodyFont?: BodyFont;
@@ -250,10 +229,6 @@ export interface Knobs {
   cornerSmoothing?: CornerSmoothing;
   borderWidth: BorderWidth;
   elevation: Elevation;
-  space: Space;
-  size: Size;
-  /** Propagating density mode. Default comfortable; compact steps space only. */
-  density: Density;
   textAccent: TextAccent;
   headingFont: HeadingFont;
   bodyFont: BodyFont;
@@ -296,9 +271,6 @@ export const defaultKnobs: Knobs = {
   cornerSmoothing: "round",
   borderWidth: "medium",
   elevation: "small",
-  space: "medium",
-  size: "medium",
-  density: "comfortable",
   textAccent: "high",
   headingFont: "sans-serif",
   bodyFont: "sans-serif",

package/src/theme/layoutTokens.ts

@@ -205,6 +205,17 @@ export function readingWidthStyle(
   return { maxWidth: `${ch}ch`, width: "100%" };
 }
 
+// ── Form readable width ───────────────────────────────────────────────────
+
+/**
+ * A form column's readable max width: wide enough for two FormGrid columns
+ * (FORM_GRID_COLLAPSE_WIDTH 480), narrow enough that a label, its field and
+ * the actions read as one group on a wide screen. Inside the 480-640 band.
+ */
+export const FORM_READABLE_WIDTH = 560;
+export const FORM_READABLE_WIDTH_MIN = 480;
+export const FORM_READABLE_WIDTH_MAX = 640;
+
 // ── Min press target (DG-LAY-04) ──────────────────────────────────────────
 
 /** Platform floor for interactive targets (Fluent/HIG web+iOS 44; M3 48 on Android). */
@@ -283,15 +294,18 @@ export const OVERLAY_ATTACH_GAP = 0;
 // ── Semantic gaps (DG-LAY-03) ─────────────────────────────────────────────
 
 /**
- * Semantic spacing roles map onto the space-knob recipes:
+ * Semantic spacing roles (SP-GAP): `tight` → `knobProps.gapSm`,
  * `within-group` → `knobProps.gap`, `between-groups` → `knobProps.gapLg`.
+ * Fixed `$space` keys; the active scale supplies their px.
  */
 export function useSemanticGaps(): {
+  tight: { gap: string };
   withinGroup: { gap: string };
   betweenGroups: { gap: string };
 } {
   const { knobProps } = useResolvedKnobs();
   return {
+    tight: knobProps.gapSm,
     withinGroup: knobProps.gap,
     betweenGroups: knobProps.gapLg,
   };

package/src/theme/layoutTokensHooks.spec.tsx

@@ -4,7 +4,7 @@ import { TestProviders } from "@multiplatform.one/test-utils";
  * viewport-driven `useLayoutSizeClass`, the pane budget `useMultiPane`, and
  * the semantic gap roles `useSemanticGaps`. Locks down: widths resolve to the
  * canonical size classes at mount, one matchMedia listener per breakpoint is
- * registered and removed, and gap roles ride the space-knob recipes.
+ * registered and removed, and gap roles are the fixed spacing roles.
  */
 
 import { act, renderHook } from "@testing-library/react";
@@ -147,13 +147,17 @@ describe("useMultiPane", () => {
 });
 
 describe("useSemanticGaps", () => {
-  it("maps within-group to knob gap and between-groups to the large gap", () => {
+  it("maps tight to gapSm, within-group to gap and between-groups to gapLg", () => {
     setViewportWidth(1000);
     const { result: knobs } = renderHook(() => useResolvedKnobs(), { wrapper: TestProviders });
     const { result } = renderHook(() => useSemanticGaps(), { wrapper: TestProviders });
+    expect(result.current.tight).toEqual(knobs.current.knobProps.gapSm);
     expect(result.current.withinGroup).toEqual(knobs.current.knobProps.gap);
     expect(result.current.betweenGroups).toEqual(knobs.current.knobProps.gapLg);
-    // The roles must differ, or grouping hierarchy is invisible.
-    expect(result.current.withinGroup.gap).not.toBe(result.current.betweenGroups.gap);
+    expect(result.current).toEqual({
+      tight: { gap: "$2" },
+      withinGroup: { gap: "$3" },
+      betweenGroups: { gap: "$5" },
+    });
   });
 });

package/src/theme/mergedTokens.ts

@@ -0,0 +1,20 @@
+import type { TamaguiInternalConfig } from "@tamagui/web";
+
+export type TokensGlobal = { __tamaguiTokensMerged?: unknown };
+
+/**
+ * The `$`-prefixed and bare token lookup `getTokenValue("$4", "size")` reads.
+ * `createTamagui` publishes it as a global beside the config, so installing a
+ * config without it would leave token reads on the previous config's values.
+ */
+export function mergedTokens(
+  config: TamaguiInternalConfig,
+): Record<string, Record<string, unknown>> {
+  const merged: Record<string, Record<string, unknown>> = {};
+  const tokens = config.tokens as unknown as Record<string, Record<string, unknown>> | undefined;
+  const parsed = config.tokensParsed as unknown as Record<string, Record<string, unknown>>;
+  for (const category of Object.keys(parsed)) {
+    merged[category] = { ...tokens?.[category], ...parsed[category] };
+  }
+  return merged;
+}