@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/figma/figmaTokens.ts

@@ -0,0 +1,503 @@
+/**
+ * Figma token export transform — the code→Figma projection for
+ * `agent-os/specs/2026-05-08-figma-v2-token-migration`.
+ *
+ * Everything here is DERIVED from the canonical theme sources at call time
+ * (no hand-copied values):
+ *
+ * - Palette ramps + shadows: `createThemesBuilder(defaultBaseTheme,
+ *   defaultAccentTheme, defaultBuilderOptions).themes()` — the exact themes
+ *   apps run, including tint text neutralization and computed tokens like
+ *   `outlineColor`.
+ * - Semantic aliases: reverse-matched per scheme against the ramp steps of
+ *   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).
+ * - Knob outputs: `resolveKnobs()` is executed per knob mode — the export
+ *   shows exactly what the runtime resolver produces.
+ * - Typography: the built `defaultHeadingFont` / `defaultBodyFont` tables
+ *   (size / lineHeight / letterSpacing / weight).
+ *
+ * The transform is pure and deterministic (no Date, no I/O) so it can be
+ * golden-tested; the runner script (`scripts/export-figma-tokens.mts`)
+ * stamps `generatedAt` when writing to disk.
+ */
+
+import { tokens } from "@tamagui/themes";
+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 { compactSizeMap, compactSpaceMap, resolveKnobs } from "../theme/resolveKnobs";
+
+// ── Names / constants ─────────────────────────────────────────
+
+/**
+ * Theme modes of the `Palette/Theme` Figma collection (spec.md §Variable
+ * Collection Structure): semantic intents take the red/yellow/green slots;
+ * the remaining stock tints are manual designer picks. 9 modes — inside
+ * Figma Pro's 10-modes-per-collection cap with 1 slot of headroom.
+ */
+export const FIGMA_THEME_MODES = [
+  "base",
+  "accent",
+  "error",
+  "success",
+  "warning",
+  "orange",
+  "blue",
+  "purple",
+  "pink",
+] as const;
+export type FigmaThemeMode = (typeof FIGMA_THEME_MODES)[number];
+
+/**
+ * Figma's per-node corner-smoothing dial value per `cornerSmoothing` knob.
+ * `smooth` = 0.6 ≈ `corner-shape: squircle` ≡ superellipse(2) ≈ Apple's
+ * continuous corners (see cornerSmoothing.ts). This is a Figma rendering
+ * constant, not a Variable — Figma cannot bind cornerSmoothing to Variables.
+ */
+export const FIGMA_CORNER_SMOOTHING: Record<string, number> = {
+  round: 0,
+  smooth: 0.6,
+};
+
+/** Tamagui token key (`1.5`, `true`) → Figma-safe variable name segment. */
+export function figmaTokenName(prefix: string, key: string): string {
+  return `${prefix}-${String(key).replace(/\./g, "-")}`;
+}
+
+// ── Output shape ──────────────────────────────────────────────
+
+export interface FigmaPaletteTheme {
+  light: string[];
+  dark: string[];
+}
+
+export interface FigmaShadows {
+  light: Record<string, string>;
+  dark: Record<string, string>;
+}
+
+export type FigmaSemanticEntry =
+  | { alias: string; light: string; dark: string }
+  | { alias: null; light: string; dark: string };
+
+export interface FigmaRadiusMode {
+  /** Tamagui radius token resolveKnobs emits for this knob mode (e.g. `$4`). */
+  token: string;
+  /** `Sizing` collection variable to alias (e.g. `radius-4`). */
+  figmaName: string;
+  px: number;
+  /** Outer/nested radius fragment (`knobProps.borderRadiusOuter`). */
+  outerToken: string;
+  outerFigmaName: string;
+  outerPx: number;
+}
+
+export interface FigmaElevationMode {
+  /** Tamagui size token backing the elevation shadow scale (null = none). */
+  sizeToken: string | null;
+  px: number | null;
+}
+
+export interface FigmaSpaceMode {
+  paddingToken: string;
+  paddingFigmaName: string;
+  gapToken: string;
+  gapFigmaName: string;
+  gapLgToken: string;
+  gapLgFigmaName: string;
+}
+
+export interface FigmaKnobsExport {
+  borderRadius: { default: Knobs["borderRadius"]; modes: Record<string, FigmaRadiusMode> };
+  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 size/space down one level (applyDensity). */
+    compact: { size: Record<string, string>; space: Record<string, string> };
+  };
+}
+
+export interface FigmaFontExport {
+  family: string;
+  size: Record<string, number>;
+  lineHeight: Record<string, number>;
+  letterSpacing: Record<string, number>;
+  weight: Record<string, string>;
+}
+
+export interface FigmaTypographyExport {
+  heading: FigmaFontExport;
+  body: FigmaFontExport;
+  /**
+   * Category font stacks (the `headingFont`/`bodyFont` knob targets), as
+   * supplied by the app config (`packages/config/fonts.ts` in this repo).
+   * `figmaFamily` is the first family of the stack — Figma cannot resolve
+   * CSS fallback chains.
+   */
+  categories: Record<string, { stack: string; figmaFamily: string }>;
+}
+
+export interface FigmaTokensExport {
+  $meta: {
+    generator: string;
+    spec: string;
+    note: string;
+  };
+  palette: {
+    themes: Record<string, FigmaPaletteTheme>;
+    shadows: FigmaShadows;
+  };
+  semantic: Record<string, FigmaSemanticEntry>;
+  sizing: Record<string, number>;
+  knobs: FigmaKnobsExport;
+  typography: FigmaTypographyExport;
+}
+
+export interface BuildFigmaTokensOptions {
+  /** Category font stacks to export (e.g. `fontFamilies` from app config). */
+  fontFamilies?: Record<string, string>;
+}
+
+// ── Internals ─────────────────────────────────────────────────
+
+type BuiltThemes = Record<string, Record<string, string | number>>;
+
+function unwrapTokenGroup(group: object | undefined): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!group) return out;
+  for (const [key, wrapper] of Object.entries(group)) {
+    const val =
+      wrapper && typeof wrapper === "object" && "val" in wrapper
+        ? (wrapper as { val: unknown }).val
+        : wrapper;
+    if (typeof val === "number") out[key] = val;
+  }
+  return out;
+}
+
+function ramp(themes: BuiltThemes, themeName: string, scheme: "light" | "dark"): string[] {
+  const key = themeName === "base" ? scheme : `${scheme}_${themeName}`;
+  const theme = themes[key];
+  if (!theme) throw new Error(`figmaTokens: built themes are missing "${key}"`);
+  const steps: string[] = [];
+  for (let i = 1; i <= 12; i++) {
+    const value = theme[`color${i}`];
+    if (typeof value !== "string") {
+      throw new Error(`figmaTokens: theme "${key}" is missing color${i}`);
+    }
+    steps.push(value);
+  }
+  return steps;
+}
+
+function shadowsOf(themes: BuiltThemes, scheme: "light" | "dark"): Record<string, string> {
+  const theme = themes[scheme];
+  const out: Record<string, string> = {};
+  for (let i = 1; i <= 6; i++) {
+    const value = theme?.[`shadow${i}`];
+    if (typeof value !== "string") {
+      throw new Error(`figmaTokens: base "${scheme}" theme is missing shadow${i}`);
+    }
+    out[`shadow${i}`] = value;
+  }
+  return out;
+}
+
+const RAMP_STEP_RE = /^color([1-9]|1[0-2])$/;
+const SHADOW_RE = /^shadow[1-6]$/;
+// Raw Radix hue steps spread into the base themes as extras (amber1,
+// blueA12, ...). They are hue scales — Figma gets those via Palette/Theme
+// modes — not semantic role tokens.
+const HUE_STEP_RE = new RegExp(`^(${[...tintHueNames].join("|")})A?\\d+$`);
+
+/**
+ * Reverse-match a semantic value against the ramp of its own theme: returns
+ * `colorN` when the value is exactly step N, else null.
+ */
+function stepAliasFor(theme: Record<string, string | number>, value: string): string | null {
+  for (let i = 1; i <= 12; i++) {
+    if (theme[`color${i}`] === value) return `color${i}`;
+  }
+  return null;
+}
+
+function deriveSemantic(themes: BuiltThemes): Record<string, FigmaSemanticEntry> {
+  const light = themes.light;
+  const dark = themes.dark;
+  if (!light || !dark) throw new Error("figmaTokens: base light/dark themes missing");
+  const out: Record<string, FigmaSemanticEntry> = {};
+  const keys = Object.keys(light)
+    .filter((key) => !RAMP_STEP_RE.test(key) && !SHADOW_RE.test(key) && !HUE_STEP_RE.test(key))
+    .filter((key) => typeof light[key] === "string" && typeof dark[key] === "string")
+    .sort();
+  for (const key of keys) {
+    const lightValue = light[key] as string;
+    const darkValue = dark[key] as string;
+    const lightAlias = stepAliasFor(light, lightValue);
+    const darkAlias = stepAliasFor(dark, darkValue);
+    const alias = lightAlias !== null && lightAlias === darkAlias ? lightAlias : null;
+    out[key] = { alias, light: lightValue, dark: darkValue };
+  }
+  return out;
+}
+
+/**
+ * `textAccent` knob → semantic text tier aliases (`text-low/medium/high`),
+ * derived by running the resolver and matching its `$token` output against
+ * the built base themes.
+ */
+function textTierEntries(themes: BuiltThemes): Record<string, FigmaSemanticEntry> {
+  const light = themes.light;
+  const dark = themes.dark;
+  const out: Record<string, FigmaSemanticEntry> = {};
+  for (const tier of ["low", "medium", "high"] as const) {
+    const resolved = resolveKnobs({ ...defaultKnobs, textAccent: tier });
+    const token = String(resolved.knobProps.textAccentColor).replace(/^\$/, "");
+    const lightValue = light[token];
+    const darkValue = dark[token];
+    if (typeof lightValue !== "string" || typeof darkValue !== "string") {
+      throw new Error(`figmaTokens: textAccent "${tier}" resolved to unknown token $${token}`);
+    }
+    const lightAlias = stepAliasFor(light, lightValue);
+    const darkAlias = stepAliasFor(dark, darkValue);
+    const alias = lightAlias !== null && lightAlias === darkAlias ? lightAlias : null;
+    out[`text-${tier}`] = { alias, light: lightValue, dark: darkValue };
+  }
+  return out;
+}
+
+function buildSizing(borderWidthModes: Record<string, number>): Record<string, number> {
+  const sizing: Record<string, number> = {};
+  const groups: Array<[string, Record<string, number>]> = [
+    ["size", unwrapTokenGroup(tokens.size)],
+    ["space", unwrapTokenGroup(tokens.space)],
+    ["radius", unwrapTokenGroup(tokens.radius)],
+    ["zIndex", unwrapTokenGroup((tokens as Record<string, object>).zIndex)],
+  ];
+  for (const [prefix, group] of groups) {
+    if (prefix !== "zIndex" && Object.keys(group).length === 0) {
+      throw new Error(`figmaTokens: @tamagui/themes tokens.${prefix} is empty`);
+    }
+    for (const [key, val] of Object.entries(group)) {
+      sizing[figmaTokenName(prefix, key)] = val;
+    }
+  }
+  // borderWidth-* mirrors the borderWidth KNOB outputs (none/small/medium/
+  // large) — the old integer 0..3 scale predates the 0.5 hairline step.
+  for (const [mode, px] of Object.entries(borderWidthModes)) {
+    sizing[`borderWidth-${mode}`] = px;
+  }
+  return sizing;
+}
+
+const RADIUS_KNOB_MODES: Knobs["borderRadius"][] = ["none", "small", "medium", "large", "full"];
+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);
+  const key = token.replace(/^\$/, "");
+  const px = radius[key];
+  if (typeof px !== "number") throw new Error(`figmaTokens: unknown radius token ${token}`);
+  return px;
+}
+
+function tokenToFigma(token: string, prefix: string): string {
+  return figmaTokenName(prefix, token.replace(/^\$/, ""));
+}
+
+/**
+ * Normalize the elevation knob output to `{ sizeToken, px }` regardless of
+ * platform branch: resolveKnobs emits Tamagui size-token strings on web and
+ * the equivalent raw numbers on native (see elevationMap in resolveKnobs.ts).
+ */
+function normalizeElevation(value: string | number | undefined): FigmaElevationMode {
+  if (value === undefined) return { sizeToken: null, px: null };
+  const size = unwrapTokenGroup(tokens.size);
+  if (typeof value === "string") {
+    const key = value.replace(/^\$/, "");
+    const px = size[key];
+    if (typeof px !== "number") throw new Error(`figmaTokens: unknown size token ${value}`);
+    return { sizeToken: value, px };
+  }
+  const entry = Object.entries(size).find(([key, px]) => px === value && key !== "true");
+  return { sizeToken: entry ? `$${entry[0]}` : null, px: value };
+}
+
+function buildKnobs(): FigmaKnobsExport {
+  const borderRadius: Record<string, FigmaRadiusMode> = {};
+  for (const mode of RADIUS_KNOB_MODES) {
+    const { knobProps } = resolveKnobs({ ...defaultKnobs, borderRadius: mode });
+    const token = String(knobProps.borderRadius.borderRadius);
+    const outerToken = String(knobProps.borderRadiusOuter.borderRadius);
+    borderRadius[mode] = {
+      token,
+      figmaName: tokenToFigma(token, "radius"),
+      px: radiusPx(token),
+      outerToken,
+      outerFigmaName: tokenToFigma(outerToken, "radius"),
+      outerPx: radiusPx(outerToken),
+    };
+  }
+
+  const borderWidth: Record<string, number> = {};
+  for (const mode of BORDER_WIDTH_KNOB_MODES) {
+    const { knobProps } = resolveKnobs({ ...defaultKnobs, borderWidth: mode });
+    borderWidth[mode] = Number(knobProps.borderRadius.borderWidth);
+  }
+
+  const elevation: Record<string, FigmaElevationMode> = {};
+  for (const mode of ELEVATION_KNOB_MODES) {
+    const { knobProps } = resolveKnobs({ ...defaultKnobs, elevation: mode });
+    elevation[mode] = normalizeElevation(knobProps.elevation as string | number | undefined);
+  }
+
+  const fontWeight: Record<string, string> = {};
+  for (const mode of FONT_WEIGHT_KNOB_MODES) {
+    const { knobProps } = resolveKnobs({ ...defaultKnobs, fontWeight: mode });
+    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 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") };
+  }
+
+  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: { ...compactSizeMap }, space: { ...compactSpaceMap } },
+    },
+  };
+}
+
+interface FontLike {
+  family?: unknown;
+  size?: Record<string, unknown>;
+  lineHeight?: Record<string, unknown>;
+  letterSpacing?: Record<string, unknown>;
+  weight?: Record<string, unknown>;
+}
+
+function numberTable(table: Record<string, unknown> | undefined, label: string) {
+  const out: Record<string, number> = {};
+  if (!table) throw new Error(`figmaTokens: font is missing ${label} table`);
+  for (const [key, value] of Object.entries(table)) {
+    const num = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(num)) out[key] = num;
+  }
+  if (Object.keys(out).length === 0) throw new Error(`figmaTokens: ${label} table is empty`);
+  return out;
+}
+
+function exportFont(font: FontLike, label: string): FigmaFontExport {
+  const weight: Record<string, string> = {};
+  for (const [key, value] of Object.entries(font.weight ?? {})) {
+    weight[key] = String(value);
+  }
+  return {
+    family: String(font.family ?? ""),
+    size: numberTable(font.size, `${label}.size`),
+    lineHeight: numberTable(font.lineHeight, `${label}.lineHeight`),
+    letterSpacing: numberTable(font.letterSpacing, `${label}.letterSpacing`),
+    weight,
+  };
+}
+
+function firstFamily(stack: string): string {
+  const first = stack.split(",")[0] ?? stack;
+  return first.trim().replace(/^['"]|['"]$/g, "");
+}
+
+// ── Entry point ───────────────────────────────────────────────
+
+export function buildFigmaTokens(options: BuildFigmaTokensOptions = {}): FigmaTokensExport {
+  const themes = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes() as BuiltThemes;
+
+  const paletteThemes: Record<string, FigmaPaletteTheme> = {};
+  for (const mode of FIGMA_THEME_MODES) {
+    paletteThemes[mode] = {
+      light: ramp(themes, mode, "light"),
+      dark: ramp(themes, mode, "dark"),
+    };
+  }
+
+  const semantic = { ...deriveSemantic(themes), ...textTierEntries(themes) };
+  const knobs = buildKnobs();
+  const sizing = buildSizing(knobs.borderWidth.modes);
+
+  const categories: FigmaTypographyExport["categories"] = {};
+  for (const [category, stack] of Object.entries(options.fontFamilies ?? {})) {
+    categories[category] = { stack, figmaFamily: firstFamily(stack) };
+  }
+
+  return {
+    $meta: {
+      generator: "public/theme/src/figma/figmaTokens.ts (buildFigmaTokens)",
+      spec: "agent-os/specs/2026-05-08-figma-v2-token-migration",
+      note: "Generated projection of the canonical theme/knob system. Do not edit by hand — rerun `pnpm exec tsx scripts/export-figma-tokens.mts`.",
+    },
+    palette: {
+      themes: paletteThemes,
+      shadows: {
+        light: shadowsOf(themes, "light"),
+        dark: shadowsOf(themes, "dark"),
+      },
+    },
+    semantic,
+    sizing,
+    knobs,
+    typography: {
+      heading: exportFont(defaultHeadingFont as FontLike, "heading"),
+      body: exportFont(defaultBodyFont as FontLike, "body"),
+      categories,
+    },
+  };
+}

package/src/font.ts

@@ -20,14 +20,12 @@ const defaults = {
     15: 114,
     16: 124,
   } as const,
-  letterSpacing: {
-    4: 1,
-    5: 3,
-    6: 3,
-    9: -2,
-    10: -3,
-    12: -4,
-  } as const,
+  // Neutral by default (LC-11): tracking is a per-family function of size,
+  // so a shared constant table is always wrong for someone — the previous
+  // Inter-ish table leaked +3px tracking into mono/script faces at $5/$6
+  // (see p-results/fixes-polish2-codeblock-density.md). Families that want
+  // optical tracking pass their own `letterSpacing` table.
+  letterSpacing: {} as Record<string | number, number>,
   weight: {
     4: "300",
   } as const,

package/src/fonts/createFontLoader.web.ts

@@ -1,9 +1,20 @@
-import "@tamagui/font-inter/css/400.css";
-import "@tamagui/font-inter/css/700.css";
 import type { FontLoader, FontLoaderConfig } from "./types";
 
 export function createFontLoader(_config: FontLoaderConfig): FontLoader {
-  // On web, fonts are loaded via CSS @font-face (side-effect imports).
-  // Inter CSS is imported above. Custom font CSS must be imported by the consumer.
+  // On web, Inter is intentionally NOT loaded here. This module previously
+  // side-effect imported @tamagui/font-inter/css/{400,700}.css, which embed
+  // the faces as base64 woff (font-display: block) — ~270 KB that vite
+  // bundles into every consumer's render-blocking extracted CSS (measured
+  // 2026-08-12: ~200 KB gz of the SPA's style.css and ~195 KB gz of the
+  // storybook iframe CSS were these two faces), duplicating the woff2
+  // binaries the shells already preload and letting the later base64
+  // declaration win the cascade over the preloaded files.
+  //
+  // Per LC-33 FONT-STABLE-MOUNT the app shell owns the fonts: declare
+  // @font-face with font-display: optional + preload the woff2 binaries in
+  // the document head (see apps/one/spa/index.html, apps/storybook
+  // .storybook/preview-head.html, and core's CreateRootLayout.web.tsx
+  // `interFonts` head flag). Custom font CSS must likewise be imported by
+  // the consumer shell, not by this package.
   return { importFonts: () => ({}) };
 }

package/src/index.ts

@@ -1,3 +1,10 @@
 export * from "./theme/index";
+export * from "./dates";
+export * from "./devWarn";
+export * from "./keyboardFocusRing";
+export * from "./menuRow";
 export * from "./font";
 export * from "./fonts/index";
+
+// Thin type re-exports so packages/apps never import @tamagui/web directly.
+export type { GenericFonts, MediaQueryKey, ThemeName } from "@tamagui/web";

package/src/keyboardFocusRing.ts

@@ -0,0 +1,45 @@
+/**
+ * Keyboard-modality tracker for manual focus-ring painting (web only).
+ *
+ * Group widgets built on roving/redirected focus (tamagui Tabs, ToggleGroup,
+ * Group-wrapped button strips) move focus from the container to the current
+ * item inside a focusin handler. Chromium drops keyboard modality on that
+ * script-initiated focus, so neither CSS :focus-visible nor tamagui's
+ * focusVisibleStyle fire for the redirected item — keyboard users get no
+ * ring (DG-A11Y-01). Components track modality with these helpers and paint
+ * the ring themselves on keyboard-origin focus.
+ */
+
+let lastInputWasKeyboard = false;
+let hooked = false;
+
+/**
+ * Install the global modality listeners. Call during render of any component
+ * that uses `wasKeyboardFocus`, so the tracker is live before the first
+ * keystroke reaches the widget. Idempotent; no-op on native/SSR.
+ */
+export function ensureKeyboardModalityTracking() {
+  if (hooked || typeof document === "undefined") return;
+  hooked = true;
+  document.addEventListener("keydown", () => (lastInputWasKeyboard = true), true);
+  document.addEventListener("pointerdown", () => (lastInputWasKeyboard = false), true);
+}
+
+/**
+ * True when the most recent user input was a key press. Call from onFocus to
+ * decide whether the focused element should paint a keyboard focus ring.
+ * Installs the global listeners on first use; safe to call on native (always
+ * false) and during SSR.
+ */
+export function wasKeyboardFocus(): boolean {
+  ensureKeyboardModalityTracking();
+  return lastInputWasKeyboard;
+}
+
+/** Standard manual ring props (mirrors the focusVisibleStyle contract). */
+export const keyboardFocusRingProps = {
+  outlineColor: "$outlineColor",
+  outlineWidth: 2,
+  outlineStyle: "solid",
+  outlineOffset: -2,
+} as const;

package/src/menuRow.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { menuRowFrame } from "./menuRow";
+
+describe("menuRowFrame (LC-16 shared menu-row geometry)", () => {
+  it("spans the overlay edge-to-edge with its own horizontal padding (SP-EDGE)", () => {
+    expect(menuRowFrame.width).toBe("100%");
+    expect(menuRowFrame.paddingHorizontal).toBe("$3");
+  });
+
+  it("keeps flat corners — the overlay container clips to the radius knob", () => {
+    expect(menuRowFrame.borderRadius).toBe(0);
+  });
+
+  it("suppresses the focus outline (row surface highlight is the indicator)", () => {
+    expect(menuRowFrame.outlineStyle).toBe("none");
+  });
+
+  it("is a centered row with a transparent base surface", () => {
+    expect(menuRowFrame.flexDirection).toBe("row");
+    expect(menuRowFrame.alignItems).toBe("center");
+    expect(menuRowFrame.backgroundColor).toBe("transparent");
+    expect(menuRowFrame.userSelect).toBe("none");
+  });
+
+  it("leaves ramp/cursor/gap/vertical sizing to consumers (not in the recipe)", () => {
+    expect(menuRowFrame).not.toHaveProperty("cursor");
+    expect(menuRowFrame).not.toHaveProperty("gap");
+    expect(menuRowFrame).not.toHaveProperty("hoverStyle");
+    expect(menuRowFrame).not.toHaveProperty("height");
+    expect(menuRowFrame).not.toHaveProperty("paddingVertical");
+  });
+});

package/src/menuRow.ts

@@ -0,0 +1,31 @@
+/**
+ * LC-16 ONE-IMPLEMENTATION — the shared menu-row frame geometry.
+ *
+ * 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.
+ *
+ * It lives in `@multiplatform.one/theme` (not `components`) because the
+ * dependency direction is `components` → `forms` → `theme`; the two forms
+ * consumers cannot import `components` without a cycle.
+ *
+ * Deliberately NOT part of the recipe — each consumer owns it, by design:
+ * - 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;
+ * - in-row gap and the state-variant model (selected/active/disabled).
+ */
+export const menuRowFrame = {
+  flexDirection: "row",
+  alignItems: "center",
+  width: "100%",
+  paddingHorizontal: "$3",
+  borderRadius: 0,
+  userSelect: "none",
+  backgroundColor: "transparent",
+  outlineStyle: "none" as any,
+} as const;