@multiplatform.one/theme 6.6.0 → 7.0.0

package/src/keyboardFocusRing.ts

@@ -36,10 +36,66 @@ export function wasKeyboardFocus(): boolean {
   return lastInputWasKeyboard;
 }
 
-/** Standard manual ring props (mirrors the focusVisibleStyle contract). */
+import { FOCUS_VISIBLE_RING } from "./theme/focusState";
+
+/**
+ * Standard manual ring props — the SAME geometry as `FOCUS_VISIBLE_RING`
+ * (2px solid `$outlineColor`, inset −2), spread here so manually-painted
+ * rings and `focusVisibleStyle` rings can never drift apart.
+ */
 export const keyboardFocusRingProps = {
-  outlineColor: "$outlineColor",
-  outlineWidth: 2,
-  outlineStyle: "solid",
-  outlineOffset: -2,
+  ...FOCUS_VISIBLE_RING,
 } as const;
+
+/**
+ * LC-71 RING-ANATOMY — CSS-synchronous ring on a composite's outer boundary.
+ *
+ * `:has(:focus-visible)` paints the same frame the keyboard heuristic would,
+ * with zero React latency (the prior `focused` JS path lagged one frame and
+ * spawned the inner-Area ring cascade). Inner targets suppress their own
+ * outline so the box carries exactly one ring. Class: `mp-composite-ring`.
+ */
+export const compositeFocusRingCss = `/* LC-71: ring on the composite outer box; never on the inner field.
+   Inset (−2px): these frames use overflow:hidden to clip children to radius,
+   which severs an outer ring. Do NOT use :has(:focus-visible) on every
+   descendant — that would ring the whole SearchInput when the clear ✕ is
+   focused (two focusables → two rings, chip-dismiss rule). */
+.mp-composite-ring:focus-visible,
+.mp-composite-ring:has(input:focus),
+.mp-composite-ring:has(textarea:focus),
+.mp-composite-ring:has(.mp-input-area:focus) {
+  outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText));
+  outline-offset: -2px;
+}
+.mp-composite-ring-deep:has(:focus-visible) {
+  outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText));
+  outline-offset: -2px;
+}
+.mp-composite-ring input,
+.mp-composite-ring textarea,
+.mp-composite-ring [contenteditable],
+.mp-input-area,
+.mp-input-area:focus,
+.mp-input-area:focus-visible {
+  outline: none !important;
+  box-shadow: none !important;
+}
+.mp-chip-dismiss:focus-visible {
+  outline: none !important;
+}
+.mp-chip-dismiss:focus-visible .mp-chip-dismiss-ring {
+  outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText));
+  outline-offset: 2px;
+}`;
+
+const COMPOSITE_RING_STYLE_ID = "mp-composite-focus-ring";
+
+/** Idempotently mount the composite-boundary focus-ring stylesheet. */
+export function ensureCompositeFocusRing(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(COMPOSITE_RING_STYLE_ID)) return;
+  const tag = document.createElement("style");
+  tag.id = COMPOSITE_RING_STYLE_ID;
+  tag.textContent = compositeFocusRingCss;
+  document.head.appendChild(tag);
+}

package/src/menuRow.spec.ts

@@ -11,8 +11,8 @@ describe("menuRowFrame (LC-16 shared menu-row geometry)", () => {
     expect(menuRowFrame.borderRadius).toBe(0);
   });
 
-  it("suppresses the focus outline (row surface highlight is the indicator)", () => {
-    expect(menuRowFrame.outlineStyle).toBe("none");
+  it("does not delete the focus ring (LC-71 — fill and ring are orthogonal)", () => {
+    expect(menuRowFrame).not.toHaveProperty("outlineStyle");
   });
 
   it("is a centered row with a transparent base surface", () => {

package/src/menuRow.ts

@@ -4,9 +4,11 @@
  * One geometry recipe for every menu/listbox row (DropdownMenu `ItemRow`,
  * Select `SelectRow`, MentionInput `MentionSuggestionItem`): the row spans
  * the full overlay width (edge-to-edge highlight, SP-EDGE), owns its
- * horizontal padding, keeps flat corners (the overlay container clips to the
- * radius knob), and suppresses the focus outline — the row surface highlight
- * IS the focus/active indicator.
+ * horizontal padding, and keeps flat corners (the overlay container clips to
+ * the radius knob — LC-72 CONTAINER-CLIP). LC-71 RING-ANATOMY: the highlight
+ * fill and the focus ring are orthogonal; consumers paint
+ * `ensureFocusVisibleRing({ outlineOffset: -2 })` on `focusVisibleStyle`
+ * (inset so the overlay clip does not sever it). Do not delete the ring.
  *
  * It lives in `@multiplatform.one/theme` (not `components`) because the
  * dependency direction is `components` → `forms` → `theme`; the two forms
@@ -27,5 +29,4 @@ export const menuRowFrame = {
   borderRadius: 0,
   userSelect: "none",
   backgroundColor: "transparent",
-  outlineStyle: "none" as any,
 } as const;

package/src/theme/Surface.spec.tsx

@@ -0,0 +1,146 @@
+/**
+ * Surface context — nested size/density step-down (LC-68).
+ */
+
+import { render, renderHook } from "@testing-library/react";
+import { createElement, type ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  Surface,
+  SurfaceContext,
+  clampSurfaceDensity,
+  clampSurfaceSize,
+  type SurfaceIntent,
+} from "./Surface";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+let originalMatchMedia: typeof window.matchMedia;
+
+beforeEach(() => {
+  originalMatchMedia = window.matchMedia;
+  window.matchMedia = vi.fn(
+    () =>
+      ({
+        matches: false,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+      }) as unknown as MediaQueryList,
+  ) as typeof window.matchMedia;
+});
+
+afterEach(() => {
+  window.matchMedia = originalMatchMedia;
+});
+
+function Probe({ onRead }: { onRead: (intent: SurfaceIntent) => void }) {
+  onRead(SurfaceContext.useStyledContext());
+  return null;
+}
+
+function renderNested(
+  outer: { size?: "small" | "medium" | "large"; density?: "compact" | "comfortable" },
+  inner: { size?: "small" | "medium" | "large"; density?: "compact" | "comfortable" },
+): SurfaceIntent {
+  let intent: SurfaceIntent | undefined;
+  render(
+    createElement(
+      Surface,
+      outer,
+      createElement(Surface, 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");
+  });
+
+  it("unset requested inherits parent", () => {
+    expect(clampSurfaceSize("unset", "small")).toBe("small");
+    expect(clampSurfaceSize("unset", "large")).toBe("large");
+  });
+
+  it("never exceeds parent", () => {
+    expect(clampSurfaceSize("large", "small")).toBe("small");
+    expect(clampSurfaceSize("medium", "small")).toBe("small");
+    expect(clampSurfaceSize("large", "medium")).toBe("medium");
+  });
+
+  it("tighter than parent is allowed", () => {
+    expect(clampSurfaceSize("small", "large")).toBe("small");
+    expect(clampSurfaceSize("medium", "large")).toBe("medium");
+    expect(clampSurfaceSize("small", "medium")).toBe("small");
+  });
+});
+
+describe("clampSurfaceDensity", () => {
+  it("unset parent is no ceiling", () => {
+    expect(clampSurfaceDensity("comfortable", "unset")).toBe("comfortable");
+  });
+
+  it("unset requested inherits parent", () => {
+    expect(clampSurfaceDensity("unset", "compact")).toBe("compact");
+  });
+
+  it("never exceeds parent; tighter is allowed", () => {
+    expect(clampSurfaceDensity("comfortable", "compact")).toBe("compact");
+    expect(clampSurfaceDensity("compact", "comfortable")).toBe("compact");
+  });
+});
+
+describe("Surface nesting (LC-68)", () => {
+  it("nested Surface size large inside small resolves small", () => {
+    expect(renderNested({ size: "small" }, { size: "large" }).size).toBe("small");
+  });
+
+  it("nested comfortable inside compact resolves compact", () => {
+    expect(renderNested({ density: "compact" }, { density: "comfortable" }).density).toBe(
+      "compact",
+    );
+  });
+
+  it("nested small inside large resolves small (tighter allowed)", () => {
+    expect(renderNested({ size: "large" }, { size: "small" }).size).toBe("small");
+  });
+});
+
+describe("useResolvedKnobs inside Surface", () => {
+  it("size=small density=compact → sizeToken $3, compact gap, small desktop control height", () => {
+    const wrapper = ({ children }: { children: ReactNode }) =>
+      createElement(Surface, { size: "small", density: "compact" }, children);
+    const { result } = renderHook(() => useResolvedKnobs(), { wrapper });
+    expect(result.current.knobProps.size).toBe("small");
+    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(28);
+  });
+
+  it("a large size request inside a medium Surface resolves medium", () => {
+    const wrapper = ({ children }: { children: ReactNode }) =>
+      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("Surface size is inherited as the subtree default (lg over global medium)", () => {
+    const wrapper = ({ children }: { children: ReactNode }) =>
+      createElement(Surface, { size: "lg" }, children);
+    const { result } = renderHook(() => useResolvedKnobs(), { wrapper });
+    expect(result.current.knobProps.size).toBe("large");
+    expect(result.current.knobProps.sizeToken).toBe("$5");
+  });
+
+  it("compact:false inside a compact Surface stays compact and still steps space", () => {
+    const wrapper = ({ children }: { children: ReactNode }) =>
+      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" });
+  });
+});

package/src/theme/Surface.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from "react";
+import { createStyledContext } from "tamagui";
+
+export type SurfaceSize = "small" | "medium" | "large";
+export type SurfaceSizeIntent = SurfaceSize | "sm" | "md" | "lg";
+export type SurfaceDensity = "compact" | "comfortable";
+export type SurfaceIntent = { size: SurfaceSize | "unset"; density: SurfaceDensity | "unset" };
+
+const SIZE_INTENT_ALIASES: Record<SurfaceSizeIntent, SurfaceSize> = {
+  sm: "small",
+  small: "small",
+  md: "medium",
+  medium: "medium",
+  lg: "large",
+  large: "large",
+};
+
+export function normalizeSurfaceSize(size: SurfaceSizeIntent): SurfaceSize {
+  return SIZE_INTENT_ALIASES[size];
+}
+
+export const SurfaceContext = createStyledContext<SurfaceIntent>({
+  size: "unset",
+  density: "unset",
+});
+
+export const SURFACE_SIZE_RANK = { unset: 99, small: 0, medium: 1, large: 2 } as const;
+export const SURFACE_DENSITY_RANK = { unset: 99, compact: 0, comfortable: 1 } as const;
+
+/**
+ * Nested surfaces/controls may inherit or go tighter (lower rank), never larger
+ * than the parent (LC-68). `unset` parent = no ceiling. `unset` requested = inherit.
+ */
+export function clampSurfaceSize(
+  requested: SurfaceSize | "unset",
+  parent: SurfaceSize | "unset",
+): SurfaceSize | "unset" {
+  if (parent === "unset") return requested;
+  if (requested === "unset") return parent;
+  return SURFACE_SIZE_RANK[requested] <= SURFACE_SIZE_RANK[parent] ? requested : parent;
+}
+
+export function clampSurfaceDensity(
+  requested: SurfaceDensity | "unset",
+  parent: SurfaceDensity | "unset",
+): SurfaceDensity | "unset" {
+  if (parent === "unset") return requested;
+  if (requested === "unset") return parent;
+  return SURFACE_DENSITY_RANK[requested] <= SURFACE_DENSITY_RANK[parent] ? requested : parent;
+}
+
+/**
+ * Declares size/density INTENT for a subtree. Nested Surfaces clamp step-down
+ * only — never raw gap tokens (LC-68, LC-69). Accepts sm/md/lg aliases.
+ */
+export function Surface({
+  size,
+  density,
+  children,
+}: {
+  size?: SurfaceSizeIntent;
+  density?: SurfaceDensity;
+  children?: ReactNode;
+}) {
+  const parent = SurfaceContext.useStyledContext();
+  const nextSize = clampSurfaceSize(size ? normalizeSurfaceSize(size) : "unset", parent.size);
+  const nextDensity = clampSurfaceDensity(density ?? "unset", parent.density);
+  return (
+    <SurfaceContext.Provider size={nextSize} density={nextDensity}>
+      {children}
+    </SurfaceContext.Provider>
+  );
+}

package/src/theme/createDefaultThemeConfig.spec.ts

@@ -0,0 +1,152 @@
+/**
+ * createDefaultThemeConfig specs — the consumer-facing batteries-included
+ * factory. Locks down the `builderOptions.getTheme` COMPOSITION contract
+ * (DF-03 / DG-A11Y-01): a consumer's partial getTheme merges over the
+ * framework default instead of replacing it, so the derived solid
+ * `$outlineColor` focus ring and the component sub-theme anchors survive,
+ * and consumer keys that resolve to undefined inside narrow sub-theme
+ * templates never leak the literal string "undefined" into theme values
+ * (the t_Button `--backgroundPress: undefined` regression).
+ *
+ * `createTamagui` is mocked pass-through: these specs pin OUR factory's
+ * theme building, not Tamagui's config processing.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("tamagui", () => ({
+  createTamagui: vi.fn((config: Record<string, unknown>) => config),
+}));
+
+// The reanimated animation driver imports react-native, which has no Node
+// build; themes are what these specs pin, so stub the driver out.
+vi.mock("./animations/index", () => ({ animations: {} }));
+
+import { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import type { GetThemeProps } from "./createThemes";
+import { setSizeRecipeInputs } from "./sizeRecipes";
+
+// Mirrors the shc app theme config: a consumer getTheme written against the
+// FULL base ramp (theme.colorN) with no outlineColor of its own. Inside
+// component sub-themes (t_Button, ...) every one of these reads undefined.
+function consumerGetTheme({ theme }: GetThemeProps): Record<string, string> {
+  return {
+    backgroundPress: theme.color5,
+    backgroundFocus: theme.color6,
+    backgroundActive: theme.color4,
+    placeholderColor: theme.color10,
+    borderColor: theme.color5,
+    borderColorHover: theme.color6,
+    borderColorFocus: theme.color7,
+    borderColorPress: theme.color7,
+    textMuted: theme.color10,
+    textSubtle: theme.color6,
+  };
+}
+
+// With createTamagui mocked pass-through, config.tamagui IS the raw config
+// object, so .themes is the raw built themes record.
+type RawThemes = Record<string, Record<string, string>>;
+
+function buildThemes(): RawThemes {
+  const config = createDefaultThemeConfig({
+    builderOptions: { getTheme: consumerGetTheme },
+  }) as unknown as { tamagui: { themes: RawThemes } };
+  return config.tamagui.themes;
+}
+
+describe("createDefaultThemeConfig — builderOptions.getTheme composition (DF-03)", () => {
+  afterEach(() => {
+    setSizeRecipeInputs();
+  });
+  const themes = buildThemes();
+
+  for (const scheme of ["light", "dark"] as const) {
+    it(`${scheme}: custom getTheme keeps the derived solid ≥3:1 $outlineColor`, () => {
+      const theme = themes[scheme];
+      expect(theme).toBeTruthy();
+      const ring = normalizeToHex(theme.outlineColor);
+      const bg1 = normalizeToHex(theme.color1);
+      const bg2 = normalizeToHex(theme.color2);
+      expect(ring).toBeTruthy();
+      expect(bg1).toBeTruthy();
+      expect(bg2).toBeTruthy();
+      const c1 = contrastRatio(relativeLuminance(ring!), relativeLuminance(bg1!));
+      const c2 = contrastRatio(relativeLuminance(ring!), relativeLuminance(bg2!));
+      expect(Math.min(c1, c2)).toBeGreaterThanOrEqual(minContrastRatio);
+    });
+  }
+
+  it("consumer keys win over the default derivation per key", () => {
+    // Default getTheme anchors textMuted at color11; the consumer moves it
+    // to color10 — composition must keep the consumer's choice.
+    for (const scheme of ["light", "dark"] as const) {
+      expect(themes[scheme].textMuted).toBe(themes[scheme].color10);
+    }
+  });
+
+  it("component sub-themes keep template values instead of literal undefined", () => {
+    const subThemeNames = Object.keys(themes).filter((name) => name.endsWith("_Button"));
+    expect(subThemeNames.length).toBeGreaterThan(0);
+    for (const name of subThemeNames) {
+      for (const [key, value] of Object.entries(themes[name])) {
+        expect(value, `${name}.${key}`).toBeDefined();
+        expect(String(value), `${name}.${key}`).not.toBe("undefined");
+      }
+    }
+  });
+
+  it("component sub-themes still derive a solid outlineColor", () => {
+    for (const name of ["light_Button", "dark_Button"]) {
+      const subTheme = themes[name];
+      expect(subTheme, name).toBeTruthy();
+      const ring = subTheme.outlineColor;
+      expect(ring, `${name}.outlineColor`).toBeTruthy();
+      expect(normalizeToHex(ring), `${name}.outlineColor solid`).toBeTruthy();
+    }
+  });
+
+  it("no built theme carries an undefined or literal-undefined value", () => {
+    for (const [name, theme] of Object.entries(themes)) {
+      for (const [key, value] of Object.entries(theme)) {
+        expect(value, `${name}.${key}`).not.toBeUndefined();
+        expect(value, `${name}.${key}`).not.toBeNull();
+        expect(String(value), `${name}.${key}`).not.toBe("undefined");
+      }
+    }
+  });
+
+  it("recipeInputs: { baseHeight: 40 } regenerates the control family on ThemeConfig, not color themes", () => {
+    const config = createDefaultThemeConfig({
+      recipeInputs: { baseHeight: 40 },
+    });
+    expect(config.recipeFamilies?.control.boxVariants.$4.height).toBe(40);
+    expect(config.recipeFamilies?.control.recipes.$4).toEqual({
+      height: 40,
+      paddingHorizontal: Math.round(40 * (12 / 32)),
+      fontSize: Math.round(40 * (14 / 32)),
+      iconSize: Math.round(40 * (16 / 32)),
+      gap: Math.round(40 * (6 / 32)),
+    });
+    expect(config.recipeInputs?.baseHeight).toBe(40);
+    const themes = (config.tamagui as unknown as { themes: RawThemes }).themes;
+    for (const [name, theme] of Object.entries(themes)) {
+      expect(theme, name).not.toHaveProperty("baseHeight");
+      expect(theme, name).not.toHaveProperty("radiusPx");
+      expect(theme, name).not.toHaveProperty("paddingHorizontal");
+      expect(theme, name).not.toHaveProperty("sizeFactors");
+    }
+  });
+
+  it("zero-options build matches the default getTheme behavior", () => {
+    const config = createDefaultThemeConfig();
+    const themes = (config.tamagui as unknown as { themes: RawThemes }).themes;
+    for (const scheme of ["light", "dark"] as const) {
+      const theme = themes[scheme];
+      expect(normalizeToHex(theme.outlineColor)).toBeTruthy();
+      expect(theme.textMuted).toBe(theme.color11);
+    }
+    expect(config.recipeFamilies?.control.boxVariants.$4.height).toBe(32);
+  });
+});

package/src/theme/createDefaultThemeConfig.ts

@@ -6,6 +6,7 @@ import { animations } from "./animations/index";
 import {
   type BaseThemeBuilderDefinition,
   type CreateThemesBuilderOptions,
+  type GetThemeProps,
   type ThemeBuilderDefinition,
   createThemesBuilder,
 } from "./createThemes";
@@ -14,7 +15,9 @@ import { defaultBaseTheme } from "./defaults/base";
 import { defaultBuilderOptions } from "./defaults/builderOptions";
 import { defaultBodyFont, defaultHeadingFont } from "./defaults/fonts";
 import type { Preset } from "./preset.types";
+import { type SizeRecipeInputs } from "./recipeInputs";
 import { type ThemeConfig, createThemeConfig } from "./shared";
+import { getGeneratedSizeRecipes, getSizeRecipeInputs, setSizeRecipeInputs } from "./sizeRecipes";
 
 export interface CreateDefaultThemeConfigOptions {
   /** Base theme palette (dark/light with optional shadows; defaults to the built-in neutral ramps) */
@@ -37,6 +40,41 @@ export interface CreateDefaultThemeConfigOptions {
   presets?: Record<string, Preset>;
   /** Default preset name to use when no `mp.preset` cookie is set */
   defaultPreset?: string;
+  /**
+   * Size-recipe inputs (LC-70). Merged over `defaultRecipeInputs`; tables are
+   * generated, written into the live aliases Button/Input already import, and
+   * attached on ThemeConfig as `recipeInputs` / `recipeFamilies`. Not written
+   * into Tamagui `themes` (those stay color palettes from createThemes /
+   * theme-builder).
+   */
+  recipeInputs?: Partial<SizeRecipeInputs>;
+}
+
+/**
+ * Compose a consumer `getTheme` WITH the framework default instead of
+ * replacing it. The default always runs first — it derives the solid ≥3:1
+ * `$outlineColor` focus ring (DG-A11Y-01), the interaction ramp and the
+ * component sub-theme border/outline anchors — then the consumer's result is
+ * merged over it per key, so a partial override keeps every derivation it
+ * doesn't explicitly change. Consumer entries that resolve to nullish are
+ * dropped: a getTheme written against the full base ramp (`theme.color5`
+ * etc.) also runs inside narrow component sub-themes where those steps don't
+ * exist, and its undefineds must not erase the defaults (DF-03).
+ */
+function composeGetTheme(
+  custom: CreateThemesBuilderOptions["getTheme"],
+): NonNullable<CreateThemesBuilderOptions["getTheme"]> {
+  const base = defaultBuilderOptions.getTheme as NonNullable<
+    CreateThemesBuilderOptions["getTheme"]
+  >;
+  if (!custom) return base;
+  return (props: GetThemeProps) => {
+    const merged: Record<string, string | number> = { ...base(props) };
+    for (const [key, value] of Object.entries(custom(props))) {
+      if (value != null) merged[key] = value;
+    }
+    return merged;
+  };
 }
 
 /**
@@ -44,18 +82,22 @@ export interface CreateDefaultThemeConfigOptions {
  * with zero options yields the framework's polished defaults — the neutral
  * Radix-mauve-curve base ramps, the solid-surface brand accent ramps, Inter
  * heading/body fonts and the interaction-ramp `getTheme` theme builder.
- * Every option overrides its piece independently: `base`, `accent` and
- * `builderOptions` each replace their default, while `fonts` are spread OVER
- * the defaults so a partial font map keeps the default heading/body.
+ * Every option overrides its piece independently: `base` and `accent` each
+ * replace their default, `fonts` are spread OVER the defaults so a partial
+ * font map keeps the default heading/body, and `builderOptions.getTheme`
+ * COMPOSES with the default (consumer keys win; framework derivations like
+ * the solid `$outlineColor` focus ring survive partial overrides).
  */
 export function createDefaultThemeConfig(
   options: CreateDefaultThemeConfigOptions = {},
 ): ThemeConfig {
+  setSizeRecipeInputs(options.recipeInputs ?? {});
   const base = options.base ?? defaultBaseTheme;
   const accent = options.accent ?? defaultAccentTheme;
   const themesBuilder = createThemesBuilder(base, accent, {
     ...defaultBuilderOptions,
     ...options.builderOptions,
+    getTheme: composeGetTheme(options.builderOptions?.getTheme),
   });
   const builtThemes: Record<string, Record<string, string>> = {
     ...themesBuilder.themes(),
@@ -105,6 +147,8 @@ export function createDefaultThemeConfig(
     {
       presets: options.presets,
       defaultPreset: options.defaultPreset,
+      recipeInputs: getSizeRecipeInputs(),
+      recipeFamilies: getGeneratedSizeRecipes().families,
     },
   );
 }

package/src/theme/createThemes.ts

@@ -58,6 +58,28 @@ export interface CreateThemesBuilderOptions {
   getTheme?: (props: GetThemeProps) => Record<string, string | number>;
 }
 
+/**
+ * Wrap a `getTheme` so entries whose value is nullish are dropped. Tamagui's
+ * ThemeBuilder spreads the result OVER the template-derived theme
+ * (`{...theme, ...getTheme(props)}`), so a key that resolves to `undefined`
+ * (e.g. a consumer getTheme reading `theme.color5` inside a narrow component
+ * sub-theme that has no colorN steps) would otherwise erase the template's
+ * real value and reach the CSS variable emitter as the literal string
+ * "undefined" — t_Button's `--backgroundPress`/`--borderColorHover` blanked
+ * pressed fills and drew phantom currentColor borders (DF-03).
+ */
+function sanitizeGetTheme(
+  getTheme: NonNullable<CreateThemesBuilderOptions["getTheme"]>,
+): NonNullable<CreateThemesBuilderOptions["getTheme"]> {
+  return (props: GetThemeProps) => {
+    const out: Record<string, string | number> = {};
+    for (const [key, value] of Object.entries(getTheme(props))) {
+      if (value != null) out[key] = value;
+    }
+    return out;
+  };
+}
+
 // Radix hue names whose sub-themes act as decorative TINTS (Tint.tsx cycling,
 // the storybook `color` global, `theme="red"` field tinting). Under a tint,
 // surfaces/borders/solids keep the hue but TEXT must stay readable neutral:
@@ -156,6 +178,7 @@ export function createThemesBuilder(
   accentTheme: ThemeBuilderDefinition,
   options?: CreateThemesBuilderOptions,
 ) {
+  const getTheme = options?.getTheme ? sanitizeGetTheme(options.getTheme) : undefined;
   const base = {
     palette: {
       dark: baseTheme.darkPalette,
@@ -317,8 +340,8 @@ export function createThemesBuilder(
   if (options?.grandChildrenThemes) {
     createThemesProps.grandChildrenThemes = options.grandChildrenThemes;
   }
-  if (options?.getTheme) {
-    createThemesProps.getTheme = options.getTheme;
+  if (getTheme) {
+    createThemesProps.getTheme = getTheme;
   }
   const initialTheme = tamaguiCreateThemes(
     createThemesProps as Parameters<typeof tamaguiCreateThemes>[0],
@@ -346,8 +369,8 @@ export function createThemesBuilder(
       if (options?.grandChildrenThemes) {
         addThemeProps.grandChildrenThemes = options.grandChildrenThemes;
       }
-      if (options?.getTheme) {
-        addThemeProps.getTheme = options.getTheme;
+      if (getTheme) {
+        addThemeProps.getTheme = getTheme;
       }
       const createdTheme = tamaguiCreateThemes(
         addThemeProps as Parameters<typeof tamaguiCreateThemes>[0],

package/src/theme/devtools/ThemeDevtoolsPanel.tsx

@@ -1230,9 +1230,13 @@ export function ThemeDevtoolsPanel({
   const handleResetToPreset = useCallback(() => {
     if (activePresetName) {
       setPreset(activePresetName);
-      setOverrides(new Set());
+    } else {
+      // Anonymous default preset (no `mp.preset` cookie): resetting must
+      // still clear the persisted overrides instead of silently no-opping.
+      setKnobs({ ...defaultKnobs });
     }
-  }, [activePresetName, setPreset]);
+    setOverrides(new Set());
+  }, [activePresetName, setPreset, setKnobs]);
 
   // -------------------------------------------------------------------------
   // Bidirectional theme sync: devtools panel ↔ website color scheme

package/src/theme/focusState.ts

@@ -46,11 +46,19 @@ export function focusRingColorMeetsContrast(ringColor: string, surfaceColor: str
   );
 }
 
+/**
+ * ONE ring geometry (DG-A11Y-01): 2px solid `$outlineColor`, inset −2.
+ * Inset is the only offset that survives fused/clipped groups (segmented
+ * controls clip children at the group radius; an outset ring paints square
+ * across the clip or disappears under `overflow: hidden`) and it matches
+ * `keyboardFocusRingProps`, the manual ring painted for roving-focus
+ * widgets — so keyboard focus reads identically everywhere.
+ */
 export const FOCUS_VISIBLE_RING = {
   outlineWidth: FOCUS_RING_MIN_WIDTH,
   outlineStyle: "solid" as const,
   outlineColor: "$outlineColor",
-  outlineOffset: 2,
+  outlineOffset: -2,
 } satisfies ControlStateProps;
 
 /**