@multiplatform.one/forms 6.6.0 → 7.0.0

package/src/Button/index.tsx

@@ -1,4 +1,5 @@
 import {
+  Children,
   createElement,
   isValidElement,
   useCallback,
@@ -9,10 +10,19 @@ import {
 } from "react";
 import {
   MIN_PRESS_TARGET,
+  ensureFocusVisibleRing,
   pressTargetHitSlop,
+  radiusClassProps,
+  recipeFamilies,
+  sizeRecipeForToken,
+  sizeRecipeFromHeight,
   solidButtonIntents,
   useResolvedKnobs,
+  type HitSlopInsets,
+  type RecipeFamilyName,
+  type SizeRecipe,
 } from "@multiplatform.one/theme";
+import { getSize } from "@tamagui/get-token";
 import { useFormField } from "../shared/utils";
 import {
   Button as TamaguiButton,
@@ -22,6 +32,7 @@ import {
   XStack,
   YStack,
   Theme,
+  getVariableValue,
   styled,
   isWeb,
   useTheme,
@@ -31,31 +42,92 @@ import type { ThemeName } from "@tamagui/web";
 import type { GestureResponderEvent } from "react-native";
 import type { AnyFormApi } from "../types";
 import { Store, useStore } from "@tanstack/react-store";
-import { getSpace } from "@tamagui/get-token";
-import { themeableVariants } from "@tamagui/stacks";
+import { getElevation, themeableVariants } from "@tamagui/stacks";
 import type { SizeTokens, VariantSpreadExtras } from "@tamagui/web";
 import { formatActionLabel } from "../actionLabel";
 import { formButtonColors, formCommonColors } from "../shared/colorRamps";
-import { warnBareDisabled, warnPositiveTabIndex } from "../shared/devWarn";
+import { warnBareDisabled, warnPositiveTabIndex, warnSizeRecipeEscape } from "../shared/devWarn";
 import { useControlGrouped } from "../shared/groupContext";
 
-/** Tamagui size-token → px (matches theme elevation comment: $2=28, $4=44). */
+/**
+ * Coordinated size recipe (Polaris slim/medium/large, Primer s/m/l, Linear
+ * 28/32/40, Spectrum S/M, M3 XS/S). Height, pad, type, and icon step together.
+ * Radius is NOT on the recipe — it stays on the borderRadius knob.
+ * Density is a different axis (pad/gap only).
+ *
+ * GENERATED (LC-75 / LC-80): Button consumes `recipeFamilies.control` — the
+ * handwritten mirror table this file used to carry drifted (md font 13 vs the
+ * recipe's 14, lg icon 18 vs 20) and is gone. `fontSize` is the recipe's px
+ * number, not a font token.
+ */
+export type ButtonSizeRecipe = SizeRecipe;
+
+export const buttonSizeRecipes: Record<string, ButtonSizeRecipe> = recipeFamilies.control.recipes;
+
+export function resolveButtonSizeRecipe(
+  size: SizeTokens | number | undefined,
+  family: RecipeFamilyName = "control",
+): ButtonSizeRecipe {
+  // Arbitrary numeric height: derive pad/font/icon/gap in ratio (the
+  // non-enumerable escape LC-80 reserves for `sizeRecipeFromHeight`).
+  if (typeof size === "number") {
+    return sizeRecipeFromHeight(size, recipeFamilies[family]?.ratios);
+  }
+  return sizeRecipeForToken(size == null ? "$true" : String(size), { family });
+}
+
+/** Density tightens pad/gap only — never height, type, or icon (density ≠ size). */
+export function buttonDensityPad(padX: number, densityTight: boolean): number {
+  return densityTight ? Math.max(8, padX - 2) : padX;
+}
+
+export function buttonDensityGap(gap: number, densityTight: boolean): number {
+  return densityTight ? Math.max(4, gap - 1) : gap;
+}
+
+/**
+ * Tamagui size-token → px (circular variant still uses the token box).
+ * Resolved from the live token scale — not a handwritten mirror of it.
+ */
 function sizeTokenPx(size: SizeTokens | number | undefined): number {
   if (typeof size === "number") return size;
   if (size == null) return MIN_PRESS_TARGET;
-  const map: Record<string, number> = {
-    $1: 20,
-    "$1.5": 24,
-    $2: 28,
-    "$2.5": 32,
-    $3: 36,
-    "$3.5": 40,
-    $4: 44,
-    $true: 44,
-    $5: 52,
-    $6: 64,
-  };
-  return map[String(size)] ?? MIN_PRESS_TARGET;
+  const resolved = getVariableValue(getSize(size));
+  return typeof resolved === "number" && Number.isFinite(resolved) ? resolved : MIN_PRESS_TARGET;
+}
+
+const PRESS_SLOP_STYLE_ID = "mp-button-press-slop";
+
+function pressSlopStylesheet(): string {
+  const rules = ["[data-mp-press-slop]{position:relative}"];
+  for (let n = 1; n <= 16; n++) {
+    rules.push(`[data-mp-press-slop="${n}"]::after{content:"";position:absolute;inset:-${n}px}`);
+  }
+  return rules.join("");
+}
+
+function ensureButtonPressSlop(): void {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(PRESS_SLOP_STYLE_ID)) return;
+  const tag = document.createElement("style");
+  tag.id = PRESS_SLOP_STYLE_ID;
+  tag.textContent = pressSlopStylesheet();
+  document.head.appendChild(tag);
+}
+
+function pressSlopProps(
+  visualPx: number,
+  enabled: boolean,
+): { "data-mp-press-slop": string } | { hitSlop: HitSlopInsets } | undefined {
+  if (!enabled || visualPx >= MIN_PRESS_TARGET) return undefined;
+  const hitSlop = pressTargetHitSlop(visualPx);
+  const outset = hitSlop.top;
+  if (outset <= 0) return undefined;
+  if (isWeb) {
+    ensureButtonPressSlop();
+    return { "data-mp-press-slop": String(outset) };
+  }
+  return { hitSlop };
 }
 
 /** DG-ACT-01 role within an ActionBar / action region. */
@@ -64,33 +136,25 @@ export type ButtonActionRole = "primary" | "secondary" | "chrome";
 type IconLike = ReactNode | ComponentType<{ size?: number }>;
 
 /** Many call sites pass Phosphor `Icon` (component) instead of `<Icon />`. */
-function normalizeButtonIcon(icon: IconLike | undefined): ReactNode {
+function normalizeButtonIcon(icon: IconLike | undefined, iconSize: number): ReactNode {
   if (icon == null || icon === false) return null;
   if (isValidElement(icon)) return icon;
   if (typeof icon === "function") {
-    return createElement(icon, { size: 16 });
+    return createElement(icon, { size: iconSize });
   }
   if (typeof icon === "object" && icon !== null && "$$typeof" in icon) {
-    return createElement(icon as unknown as ComponentType<{ size?: number }>, { size: 16 });
+    return createElement(icon as unknown as ComponentType<{ size?: number }>, { size: iconSize });
   }
   return icon;
 }
 
 const getButtonSized = (val: SizeTokens | number, { props }: VariantSpreadExtras<any>) => {
   if (!val || props.circular) return;
-  // DG-LAY-04 / SP-FIXED: size knob may shrink chrome ($3=36) but the press
-  // target never drops below 44 — minHeight holds the floor.
-  if (typeof val === "number") {
-    return {
-      paddingHorizontal: val * 0.25,
-      height: Math.max(val, MIN_PRESS_TARGET),
-      minHeight: MIN_PRESS_TARGET,
-    };
-  }
+  const recipe = resolveButtonSizeRecipe(val);
   return {
-    paddingHorizontal: getSpace(val),
-    height: val,
-    minHeight: MIN_PRESS_TARGET,
+    paddingHorizontal: recipe.paddingHorizontal,
+    height: recipe.height,
+    minHeight: recipe.height,
   };
 };
 
@@ -100,9 +164,45 @@ const textAccentLow = {
   press: formButtonColors.textLow.active,
 } as const;
 
+/** LC-82 TEXT-RIDES-TEXT: bare string/number children are legal only inside Text. */
+const isBareTextChild = (child: unknown): child is string | number =>
+  typeof child === "string" || typeof child === "number";
+
+/**
+ * LC-82 TEXT-RIDES-TEXT (catalog arm): multi-child arrays are the trap — the
+ * singleton auto-wrap misses `{label}{cond ? suffix : ""}` (TWO string
+ * children), which web renders and native rejects ("Text strings must be
+ * rendered within a <Text> component"), silently dropping the label. Each run
+ * of adjacent bare string/number children coalesces into one concatenated
+ * label handed to the same Text wrapper the singleton path uses; element
+ * children pass through untouched, order preserved (keys via Children.toArray).
+ */
+function wrapBareTextChildren(
+  children: ReturnType<typeof Children.toArray>,
+  renderLabel: (label: string, key: string) => ReactNode,
+): ReactNode[] {
+  const out: ReactNode[] = [];
+  let run: string | undefined;
+  let runIndex = 0;
+  const flushRun = () => {
+    if (run !== undefined && run !== "") out.push(renderLabel(run, `lc35-run-${runIndex++}`));
+    run = undefined;
+  };
+  for (const child of children) {
+    if (isBareTextChild(child)) {
+      run = (run ?? "") + String(child);
+    } else {
+      flushRun();
+      out.push(child);
+    }
+  }
+  flushRun();
+  return out;
+}
+
 const dummyStore = new Store({ isValid: true });
 
-const ButtonFrame = styled(View, {
+export const ButtonFrame = styled(View, {
   name: "Button",
   role: "button",
   tabIndex: 0,
@@ -113,9 +213,11 @@ const ButtonFrame = styled(View, {
   flexDirection: "row",
   backgroundColor: "$background",
   borderColor: "$borderColor",
+  outlineWidth: 0,
   hoverStyle: {
     backgroundColor: "$backgroundHover",
   },
+  focusStyle: { outlineWidth: 0 },
   variants: {
     outlined: {
       true: {
@@ -125,8 +227,25 @@ const ButtonFrame = styled(View, {
         pressStyle: { backgroundColor: "transparent" },
       },
     },
+    selected: {
+      true: {
+        backgroundColor: "$backgroundPress",
+        hoverStyle: { backgroundColor: "$backgroundPress" },
+        pressStyle: { backgroundColor: "$backgroundPress" },
+      },
+    },
     circular: themeableVariants.circular,
     chromeless: themeableVariants.chromeless,
+    // LC-18: `styled(View)` inherits no variants, so without this the
+    // `elevation={knobProps.elevation}` the frame passes below (and the
+    // per-intent `Button: { elevation }` overrides in defaultIntents) were
+    // silently dropped — the elevation knob never reached any Button. Same
+    // token→shadow mapping the tamagui stacks use; `chromeless` still zeroes
+    // the shadow (its shadowColor: transparent rides the later consumer prop).
+    elevation: {
+      "...size": getElevation,
+      ":number": getElevation,
+    },
     size: {
       "...size": getButtonSized,
     },
@@ -154,6 +273,17 @@ export interface ButtonProps extends Omit<TamaguiButtonProps, "form" | "icon" |
   icon?: IconLike;
   iconAfter?: IconLike;
   compact?: boolean;
+  /**
+   * LC-71 / Spectrum ActionButton / Polaris `pressed`: selected is FILL, never
+   * a second ring. Keyboard focus still paints the LC-71 outline on the frame.
+   */
+  selected?: boolean;
+  /**
+   * LC-73: nested surfaces (dialog, overlay, calendar) paint `nestedControl`
+   * (below the 44px chrome floor) and restore press with hitSlop. Does not
+   * change page-level `circularPressFloor` (toolbar icon wells stay 44px).
+   */
+  nested?: boolean;
   /**
    * DG-ACT-02 / DG-COPY-03 — structured label. Used when `children` is omitted.
    * Prefer `{ verb, noun }` over free-form strings for chrome actions.
@@ -182,6 +312,18 @@ export interface ButtonProps extends Omit<TamaguiButtonProps, "form" | "icon" |
    * control height and wraps into cramped multi-line type.
    */
   disabledReasonPlacement?: "below" | "inline";
+  /**
+   * Opt-in to an explicit numeric `height` / `paddingHorizontal`. Required
+   * when those props are numbers; without it DEV-warns `size-recipe-escape`
+   * and the size recipe still wins (LC-75).
+   */
+  sizeRecipeEscape?: string;
+  /**
+   * Size-recipe FAMILY (LC-80): same heights, different ratios.
+   * `controlCompact` tightens pad/font/icon/gap at the same height — a theme
+   * opt-in, never a per-component tweak. Defaults to `control`.
+   */
+  recipeFamily?: RecipeFamilyName;
 }
 
 export function Button({
@@ -203,11 +345,19 @@ export function Button({
   icon,
   iconAfter,
   compact,
+  selected,
+  nested = false,
+  circular,
+  chromeless,
   verb,
   noun,
   actionRole,
   disabledReason,
   disabledReasonPlacement = "below",
+  sizeRecipeEscape,
+  recipeFamily = "control",
+  height: heightProp,
+  paddingHorizontal: paddingHorizontalProp,
   ...props
 }: ButtonProps) {
   const { resolvedForm: formFromHook } = useFormField({ form: formProp });
@@ -226,6 +376,30 @@ export function Button({
     component: "Button",
     value: typeof tabIndex === "number" ? tabIndex : undefined,
   });
+  warnSizeRecipeEscape({
+    height: heightProp,
+    paddingHorizontal: paddingHorizontalProp,
+    sizeRecipeEscape,
+    component: "Button",
+    id:
+      typeof (props as { id?: string }).id === "string" ? (props as { id?: string }).id : undefined,
+  });
+  const sizeRecipeEscaped =
+    typeof sizeRecipeEscape === "string" && sizeRecipeEscape.trim().length > 0;
+  const sizeRecipeEscapeOverride = sizeRecipeEscaped
+    ? {
+        ...(typeof heightProp === "number" ? { height: heightProp } : undefined),
+        ...(typeof paddingHorizontalProp === "number"
+          ? { paddingHorizontal: paddingHorizontalProp }
+          : undefined),
+      }
+    : undefined;
+  const passthroughSizeProps = {
+    ...(typeof heightProp !== "number" && heightProp != null ? { height: heightProp } : undefined),
+    ...(typeof paddingHorizontalProp !== "number" && paddingHorizontalProp != null
+      ? { paddingHorizontal: paddingHorizontalProp }
+      : undefined),
+  };
 
   const { isValid } = useStore(
     (resolvedForm?.store ?? dummyStore) as Store<{ isValid: boolean }>,
@@ -238,22 +412,29 @@ export function Button({
     (warning && "warning") ||
     (success && "success") ||
     undefined;
+  // compact is density (pad/gap), not a size step — do not pass it through
+  // useResolvedKnobs, which would also step knobs.size.
   const { knobProps, control, text, disabledState } = useResolvedKnobs({
     intent,
     component: "Button",
-    compact,
   });
   // Ring color resolved OUTSIDE the intent <Theme> wrapper below — the
   // page-scope `$outlineColor` literal (DG-A11Y-01; see focusVisibleStyle).
   const parentScopeTheme = useTheme();
   const pageOutlineColor = parentScopeTheme.outlineColor?.val as string | undefined;
   const grouped = useControlGrouped();
+  const sizeProp = (props as { size?: SizeTokens | number }).size;
+  const resolvedSize = sizeProp ?? knobProps.sizeToken;
+  const recipe = resolveButtonSizeRecipe(resolvedSize, recipeFamily);
+  const densityTight = compact === true;
+  const padX = buttonDensityPad(recipe.paddingHorizontal, densityTight);
+  const innerGap = buttonDensityGap(recipe.gap, densityTight);
   if (skeleton) {
     return (
       <View
         {...knobProps.borderRadius}
         backgroundColor="$gray5"
-        height={knobProps.sizeToken}
+        height={nested ? knobProps.nestedControl.px : recipe.height}
         width={120}
         opacity={0.5}
         {...props}
@@ -316,11 +497,19 @@ export function Button({
   const labelFromParts =
     children == null && verb != null ? formatActionLabel({ verb, noun }) : null;
   const resolvedChildren = children ?? labelFromParts;
+  const ariaPressedProp = (props as { "aria-pressed"?: boolean | "true" | "false" })[
+    "aria-pressed"
+  ];
+  const isSelected =
+    selected ?? (ariaPressedProp === true || ariaPressedProp === "true" ? true : undefined);
+  const selectedFill = Boolean(isSelected) && !isDisabled;
+  const iconSize = nested
+    ? Math.min(recipe.iconSize, Math.max(12, Math.round(knobProps.nestedControl.px * 0.45)))
+    : recipe.iconSize;
 
-  const textContent = loading ? (
-    <Spinner size="small" />
-  ) : typeof resolvedChildren === "string" ? (
+  const renderLabelText = (label: string | number, key?: string) => (
     <SizableText
+      key={key}
       userSelect="none"
       flexGrow={0}
       flexShrink={1}
@@ -328,22 +517,37 @@ export function Button({
       whiteSpace="nowrap"
       overflow="hidden"
       {...knobProps.body}
+      {...(nested ? knobProps.label : { fontSize: recipe.fontSize })}
       {...(textColor ? { color: textColor } : undefined)}
       // LC-40: on the washed disabled chrome the label leaves the on-fill
       // foreground and pins to the lowest AA tier (keepLabel keeps >=4.5:1).
       {...(isDisabled ? disabledState.textKnobProps : undefined)}
       transition={knobProps.transition}
     >
-      {resolvedChildren}
+      {label}
     </SizableText>
+  );
+  // LC-82 TEXT-RIDES-TEXT: wrap ALL bare string/number children — the
+  // array path (coalesced runs), not just the singleton case.
+  const flattenedChildren = Array.isArray(resolvedChildren)
+    ? Children.toArray(resolvedChildren)
+    : null;
+  const textContent = loading ? (
+    <Spinner size="small" />
+  ) : isBareTextChild(resolvedChildren) ? (
+    renderLabelText(resolvedChildren)
+  ) : flattenedChildren?.some(isBareTextChild) ? (
+    wrapBareTextChildren(flattenedChildren, renderLabelText)
   ) : (
     resolvedChildren
   );
 
   const hasIcon = icon || iconAfter;
-  const iconElement = icon ? <View flexShrink={0}>{normalizeButtonIcon(icon)}</View> : null;
+  const iconElement = icon ? (
+    <View flexShrink={0}>{normalizeButtonIcon(icon, iconSize)}</View>
+  ) : null;
   const iconAfterElement = iconAfter ? (
-    <View flexShrink={0}>{normalizeButtonIcon(iconAfter)}</View>
+    <View flexShrink={0}>{normalizeButtonIcon(iconAfter, iconSize)}</View>
   ) : null;
 
   const explainedDisable = Boolean(disabledReason?.trim()) && Boolean(isDisabled);
@@ -351,13 +555,15 @@ export function Button({
   const reasonId = explainedDisable
     ? `${(props as { id?: string }).id ?? generatedId}-disabled-reason`
     : undefined;
-  const isCircular = Boolean((props as { circular?: boolean }).circular);
-  const resolvedSize = (props as { size?: SizeTokens | number }).size ?? knobProps.sizeToken;
-  const visualPx = sizeTokenPx(resolvedSize);
+  const isCircular = Boolean(circular);
+  const circularTokenPx = sizeTokenPx(resolvedSize);
+  const visualPx = nested ? knobProps.nestedControl.px : recipe.height;
   // Circular tokens below 44 need an explicit box floor (circular variant also
   // sets maxWidth/maxHeight to the token). hitSlop covers native/touch leftovers.
+  // Nested circulars skip this — they paint nestedControl and restore press
+  // with slop (LC-73). Page-level toolbar wells keep the 44px painted floor.
   const circularPressFloor =
-    isCircular && visualPx < MIN_PRESS_TARGET
+    isCircular && circularTokenPx < MIN_PRESS_TARGET
       ? {
           width: MIN_PRESS_TARGET,
           height: MIN_PRESS_TARGET,
@@ -365,20 +571,52 @@ export function Button({
           minHeight: MIN_PRESS_TARGET,
           maxWidth: MIN_PRESS_TARGET,
           maxHeight: MIN_PRESS_TARGET,
-          hitSlop: pressTargetHitSlop(visualPx),
+          hitSlop: pressTargetHitSlop(circularTokenPx),
         }
       : isCircular
         ? { minWidth: MIN_PRESS_TARGET, minHeight: MIN_PRESS_TARGET }
-        : { minHeight: MIN_PRESS_TARGET };
-  // Axiom 3 NULL / LC-18: `circular` is a SHAPE eject, not a radius eject —
-  // a Button is R-SCALE, so in the square world (`borderRadius:none`) it goes
-  // square like every other control. The tamagui `circular` variant expands
-  // to a ~100000 radius that beats a plain borderRadius prop, so this rides
-  // an inline style (same idiom as the DatePicker day cell). Without it every
-  // `circular` Button in the catalog is an undeclared knob-immune shape
-  // (D-09 / LC-60 sweep finding: Pagination prev/next).
-  const circularSquareAtNone =
-    isCircular && knobProps.pointy ? { style: { borderRadius: 0 } } : null;
+        : undefined;
+  const nestedFloor = nested
+    ? {
+        height: visualPx,
+        minHeight: visualPx,
+        maxHeight: visualPx,
+        ...(isCircular
+          ? {
+              width: visualPx,
+              minWidth: visualPx,
+              maxWidth: visualPx,
+              borderRadius: 100000,
+            }
+          : {}),
+        "data-nested-px": String(visualPx),
+        ...pressSlopProps(visualPx, true),
+      }
+    : undefined;
+  const pageSlop = !nested && !isCircular && !grouped ? pressSlopProps(visualPx, true) : undefined;
+  // LC-18 scope (owner ruling 2026-08-13, supersedes the D-09-era inline
+  // squaring): `circular` is an explicit consumer SHAPE eject, so the tamagui
+  // `circular` variant's ~100000 radius keeps winning over
+  // `knobProps.borderRadius` — INCLUDING at `borderRadius: none`. A circular
+  // Button (favorite heart, Pagination prev/next, toolbar icon wells) keeps
+  // its circle in the square world, the same way consumer `{...props}` win
+  // last per STD-EJECT-LAST; every other channel on the frame (size,
+  // elevation, border width, motion, disabled wash) still follows the knobs,
+  // and the default/outlined frame goes fully square at `none` via the knob
+  // fragment below.
+  const selectedHoverFill = selectedFill
+    ? outlined
+      ? "$backgroundHover"
+      : "$backgroundPress"
+    : outlined
+      ? "transparent"
+      : "$backgroundHover";
+  const selectedPressFill = selectedFill
+    ? "$backgroundPress"
+    : outlined
+      ? "transparent"
+      : "$backgroundPress";
+  const restFill = selectedFill ? (outlined ? "$background" : "$backgroundPress") : undefined;
   const buttonElement = (
     <ButtonFrame
       // DG-ST-03: an explained disable is aria-disabled (focusable, press
@@ -388,10 +626,21 @@ export function Button({
       transition={knobProps.transition}
       {...knobProps.borderRadius}
       borderWidth={resolvedBorderWidth}
-      size={knobProps.sizeToken}
+      size={resolvedSize}
       elevation={knobProps.elevation}
       outlined={outlined}
+      circular={!nested && isCircular ? true : undefined}
+      chromeless={selectedFill ? false : chromeless}
+      selected={selectedFill || undefined}
       {...(outlined ? { variant: "outlined" as const } : undefined)}
+      {...(!isCircular || nested
+        ? {
+            paddingHorizontal: padX,
+            height: visualPx,
+            minHeight: visualPx,
+          }
+        : undefined)}
+      {...(restFill ? { backgroundColor: restFill } : undefined)}
       // Solid-intent sub-themes carry the on-fill foreground as `$color`
       // (LC-05); outlined frames sit on the page, so re-anchor inherited
       // text/icon color (currentColor) to the hue's readable text tier.
@@ -419,34 +668,63 @@ export function Button({
           }
         : undefined)}
       hoverStyle={{
-        backgroundColor: outlined ? "transparent" : "$backgroundHover",
-        ...(outlined ? { borderColor: "$borderColorHover" } : undefined),
+        backgroundColor: selectedHoverFill,
+        ...(outlined && !selectedFill ? { borderColor: "$borderColorHover" } : undefined),
         ...control.hoverKnobProps,
         ...text.hoverKnobProps,
+        ...(selectedFill ? { backgroundColor: selectedHoverFill } : undefined),
       }}
       pressStyle={{
-        backgroundColor: outlined ? "transparent" : "$backgroundPress",
-        ...(outlined ? { borderColor: "$borderColorPress" } : undefined),
+        backgroundColor: selectedPressFill,
+        ...(outlined && !selectedFill ? { borderColor: "$borderColorPress" } : undefined),
         ...control.pressKnobProps,
         ...text.pressKnobProps,
+        ...(selectedFill ? { backgroundColor: selectedPressFill } : undefined),
       }}
-      focusStyle={{}}
-      // DG-A11Y-01: the house focus-visible ring (recipe-supplied, ≥2px) —
-      // was `{{}}`, which left only the browser default. The color is the
-      // PARENT-scope `$outlineColor` literal: intent buttons re-theme the
-      // frame (<Theme name="accent">…), and those sub-themes derive a ring
-      // for their own inverted surfaces — invisible on the page the ring
-      // actually draws on (measured 1.17:1 on the accent pagination button).
-      focusVisibleStyle={{
+      focusStyle={{ outlineWidth: 0 }}
+      // DG-A11Y-01 / LC-71: house keyboard ring (≥2px `$outlineColor`) on the
+      // whole painted frame. Rest and mouse-focus paint none. Parent-scope
+      // `$outlineColor` literal: intent buttons re-theme the frame, and those
+      // sub-themes derive a ring for their own inverted surfaces — invisible
+      // on the page the ring actually draws on (measured 1.17:1 on the accent
+      // pagination button).
+      focusVisibleStyle={ensureFocusVisibleRing({
         ...control.focusVisibleKnobProps,
         ...(pageOutlineColor ? { outlineColor: pageOutlineColor } : undefined),
-      }}
+      })}
       onPress={handlePress}
       {...(isWeb ? { onKeyDown: handleKeyDown as unknown as () => void } : undefined)}
       {...(tabIndex != null ? { tabIndex } : undefined)}
+      gap={hasIcon && (resolvedChildren || textContent) ? innerGap : undefined}
+      // STD-EJECT-LAST: knob fragments and internal defaults (radius/size/
+      // elevation/gap above) sit BEFORE the consumer spread so `{...props}`
+      // stays the one styling eject. The spreads after it are not defaults:
+      // the press-target floor must beat the `circular` variant expansion
+      // (which rides the consumer's own `circular` prop inside `{...props}`),
+      // the LC-60 identity declaration licenses that same shape eject so the
+      // radius:none sweep does not flatten circles (owner ruling 2026-08-13),
+      // and the explained-disable / grouped branches are state & group
+      // contracts (DG-ST-03, R-OUTER), not restylable chrome.
       {...props}
-      {...circularPressFloor}
-      {...circularSquareAtNone}
+      {...passthroughSizeProps}
+      {...sizeRecipeEscapeOverride}
+      {...(nested ? nestedFloor : isCircular ? circularPressFloor : pageSlop)}
+      {...(selectedFill && !isDisabled
+        ? {
+            backgroundColor: restFill,
+            hoverStyle: {
+              ...control.hoverKnobProps,
+              ...text.hoverKnobProps,
+              backgroundColor: selectedHoverFill,
+            },
+            pressStyle: {
+              ...control.pressKnobProps,
+              ...text.pressKnobProps,
+              backgroundColor: selectedPressFill,
+            },
+          }
+        : undefined)}
+      {...(isCircular && !grouped ? radiusClassProps("R-IDENTITY", "circular Button") : undefined)}
       {...(explainedDisable
         ? {
             // No `title`: hover-only reveals are banned on disabled controls
@@ -475,8 +753,12 @@ export function Button({
             height: "100%",
           }
         : undefined)}
-      gap={hasIcon && (resolvedChildren || textContent) ? "$2" : undefined}
       {...(resolvedRole ? { "data-mp-action-role": resolvedRole } : undefined)}
+      data-mp-button-height={String(
+        nested ? visualPx : isCircular ? Math.max(circularTokenPx, MIN_PRESS_TARGET) : visualPx,
+      )}
+      data-mp-density={densityTight ? "compact" : knobProps.density}
+      {...(selectedFill ? { "aria-pressed": true, "data-mp-selected": "true" } : undefined)}
     >
       {iconElement}
       {textContent}