@oxy.so/bloom 5.4.0 → 6.0.0

package/src/button/Button.tsx

@@ -1,3 +1,4 @@
+import { useSurfaceLayer } from '../surface/use-surface-layer';
 import type { LinkButtonProps } from './types';
 import React, { forwardRef, useMemo, useRef, useEffect, memo, type ComponentType } from 'react';
 import { resolveIconSlot } from '../icons/render-icon';
@@ -20,20 +21,7 @@ import { useBloomAppearance } from '../appearance/context';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography/Typography';
 import { useInteractionState } from '../hooks/use-interaction-state';
-import {
-  BUTTON_GEOMETRY,
-  BUTTON_RADIUS,
-  BUTTON_SHADOW,
-  ICON_BUTTON_ICON_SIZE,
-  LINK_BUTTON_GAP,
-  isIconComponent,
-  resolveButtonRecipe,
-  BUTTON_SIZE_ALIAS,
-  resolveButtonGeometry,
-  resolveButtonPalette,
-  resolveButtonUnderline,
-  type ButtonResolvedSize,
-} from './shared';
+import { BUTTON_RADIUS, BUTTON_SHADOW, ICON_BUTTON_ICON_SIZE, LINK_BUTTON_GAP, isIconComponent, resolveLinkButtonPalette, resolveButtonGeometry, resolveButtonPalette, resolveButtonUnderline, type ButtonResolvedSize } from './shared';
 import type { ButtonProps } from './types';
 
 /** Raw text descendants need a native Text host; layout content stays unwrapped. */
@@ -82,9 +70,6 @@ export type {
  * Native fork of the button. Geometry and every state's colours come
  * from `./shared`, the same table `Button.web.tsx` reads.
  *
- * The web fork's `outline | link | destructive` are real variants here too:
- * `outline` and `link` share `secondary`/`text`'s palette, `destructive` paints
- * the negative gradient.
  */
 
 /**
@@ -206,7 +191,6 @@ const ButtonComponent = forwardRef<View, ButtonProps>(function ButtonComponent({
   pressed: togglePressed,
   stopPropagation = false,
   appearance: appearanceProp,
-  variant: variantProp,
   tone: toneProp,
   size: sizeProp,
   style,
@@ -220,7 +204,7 @@ const ButtonComponent = forwardRef<View, ButtonProps>(function ButtonComponent({
   renderLeadingIcon,
   renderTrailingIcon,
   iconOnly = false,
-  linkTone = 'primary',
+  linkTone,
   underline,
   textVariant,
   numberOfLines,
@@ -237,20 +221,20 @@ const ButtonComponent = forwardRef<View, ButtonProps>(function ButtonComponent({
   'aria-haspopup': ariaHasPopup,
 }, ref) {
   const theme = useTheme();
-  const recipe = resolveButtonRecipe(variantProp);
-  const appearance = appearanceProp ?? recipe.appearance;
-  const { size, tone } = useBloomAppearance({ size: sizeProp ? BUTTON_SIZE_ALIAS[sizeProp] : undefined, tone: toneProp ?? (variantProp ? recipe.tone : undefined) }, { size: 'md', tone: 'accent' });
+  const layer = useSurfaceLayer();
+  const appearance = appearanceProp ?? 'solid';
+  const { size, tone } = useBloomAppearance({ size: sizeProp, tone: toneProp }, { size: 'md', tone: 'accent' });
   const geometry = resolveButtonGeometry(size, textVariant);
-  const isSquare = iconOnly || variantProp === 'icon' || sizeProp === 'icon' || (icon != null && children == null);
+  const isSquare = iconOnly || (icon != null && children == null);
   const isIconVariant = isSquare;
-  const isLink = appearance === 'plain' && (href != null || variantProp === 'link');
+  const isLink = appearance === 'plain' && (href != null || linkTone != null);
   const isInteractionBlocked = disabled || loading;
   const iconSize = typeof iconSizeProp === 'number' && Number.isFinite(iconSizeProp) && iconSizeProp > 0 ? iconSizeProp : isIconVariant ? ICON_BUTTON_ICON_SIZE[size] : geometry.iconSize;
   const palette = useMemo(
-    () => variantProp === 'link' && appearanceProp == null && toneProp == null ? resolveButtonPalette('link', theme, linkTone) : variantProp === 'inverse' && appearanceProp == null && toneProp == null ? resolveButtonPalette('inverse', theme) : resolveButtonPalette(appearance, theme, tone, colors),
-    [appearance, theme, tone, variantProp, appearanceProp, toneProp, linkTone, colors],
+    () => isLink && linkTone != null && toneProp == null ? resolveLinkButtonPalette(theme, linkTone) : resolveButtonPalette(appearance, theme, tone, colors, layer.fill),
+    [appearance, theme, tone, toneProp, isLink, linkTone, colors, layer.fill],
   );
-  const underlineMode = resolveButtonUnderline(isLink ? 'link' : 'primary', underline);
+  const underlineMode = resolveButtonUnderline(isLink, underline);
 
   // Pressed state drives the ACTIVE palette. Tracked through state rather than
   // Pressable's function-form `style`, which NativeWind's css-interop swallows
@@ -468,55 +452,54 @@ const styles = StyleSheet.create({
 export const Button = memo(ButtonComponent);
 Button.displayName = 'Button';
 
-export const PrimaryButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="primary" />
+export const PrimaryButton = memo((props: ButtonProps) => (
+  <Button appearance="solid" tone="accent" {...props} />
 ));
 PrimaryButton.displayName = 'PrimaryButton';
 
-export const SecondaryButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="secondary" />
+export const SecondaryButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} />
 ));
 SecondaryButton.displayName = 'SecondaryButton';
 
-export const IconButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="icon" />
+export const IconButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} iconOnly />
 ));
 IconButton.displayName = 'IconButton';
 
-export const GhostButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="ghost" />
+export const GhostButton = memo((props: ButtonProps) => (
+  <Button appearance="subtle" tone="accent" {...props} />
 ));
 GhostButton.displayName = 'GhostButton';
 
-export const InverseButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="inverse" />
-));
+export const InverseButton = memo((props: ButtonProps) => {
+  const theme = useTheme();
+  return <Button appearance="solid" tone="neutral" colors={props.appearance == null && props.tone == null ? { background: theme.colors.text, foreground: theme.colors.background } : undefined} {...props} />;
+});
 InverseButton.displayName = 'InverseButton';
 
-export const TextButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="text" />
+export const TextButton = memo((props: ButtonProps) => (
+  <Button appearance="plain" tone="accent" {...props} />
 ));
 TextButton.displayName = 'TextButton';
 
-// Web/shadcn-aligned variants. On native they normalize to existing primitives
-// (`outline → secondary`, `link → text`, `destructive → primary` tinted with the
-// negative token) inside `Button`, so these stay API-parallel with the web fork.
-export const OutlineButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="outline" />
+// Named compositions share the canonical appearance and tone axes.
+export const OutlineButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} />
 ));
 OutlineButton.displayName = 'OutlineButton';
 
 /**
  * `LinkButton`: an inline text action — no fill, no border, the label
- * (plus icons) in the accent or secondary colour. `variant` is its colour; pass
+ * (plus icons) in the accent or secondary colour. `linkTone` is its colour; pass
  * `href` to open a URL.
  */
-export const LinkButton = memo(({ variant = 'primary', ...props }: LinkButtonProps) => (
-  <Button {...props} variant="link" linkTone={variant} />
+export const LinkButton = memo(({ linkTone = 'primary', ...props }: LinkButtonProps) => (
+  <Button appearance="plain" {...props} linkTone={linkTone} />
 ));
 LinkButton.displayName = 'LinkButton';
 
-export const DestructiveButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="destructive" />
+export const DestructiveButton = memo((props: ButtonProps) => (
+  <Button appearance="solid" tone="danger" {...props} />
 ));
 DestructiveButton.displayName = 'DestructiveButton';

package/src/button/Button.web.tsx

@@ -1,3 +1,5 @@
+import { useSurfaceRefraction } from '../surface/web-refraction';
+import { useSurfaceLayer } from '../surface/use-surface-layer';
 import { useButtonLayout } from './use-button-layout.web';
 import { useLongPress } from './use-long-press.web';
 import { resolveSurfaceOptics } from '../surface/shared';
@@ -25,21 +27,7 @@ import {
   interactiveWebCss,
   useInteractiveWebCss,
 } from '../styles/interactive-web-css';
-import {
-  BUTTON_RADIUS,
-  BUTTON_SHADOW,
-  BUTTON_TRANSITION_MS,
-  ICON_BUTTON_ICON_SIZE,
-  LINK_BUTTON_GAP,
-  LINK_BUTTON_UNDERLINE_OFFSET,
-  isIconComponent,
-  resolveButtonGeometry,
-  resolveButtonRecipe,
-  BUTTON_SIZE_ALIAS,
-  resolveButtonPalette,
-  resolveButtonUnderline,
-  type ButtonResolvedSize,
-} from './shared';
+import { BUTTON_RADIUS, BUTTON_SHADOW, BUTTON_TRANSITION_MS, ICON_BUTTON_ICON_SIZE, LINK_BUTTON_GAP, LINK_BUTTON_UNDERLINE_OFFSET, isIconComponent, resolveButtonGeometry, resolveLinkButtonPalette, resolveButtonPalette, resolveButtonUnderline } from './shared';
 import type { ButtonIconComponent, ButtonProps } from './types';
 
 export type {
@@ -124,6 +112,7 @@ export const BLOOM_BUTTON_CSS = interactiveWebCss({
 }
 ${surfaceMaterialCss('.bloom-btn--surface', 'var(--bloom-btn-bg)', `background-color ${T} ease`)}
 .bloom-btn--surface { background: transparent !important; }
+.bloom-btn--surface::before { inset: 0; }
 .bloom-btn--surface${NOT_DISABLED}:hover::after { background-color: var(--bloom-btn-bg-hover); }
 .bloom-btn--surface${NOT_DISABLED}:active::after { background-color: var(--bloom-btn-bg-active); }
 .bloom-btn--surface:disabled:not([aria-busy="true"])::after,
@@ -166,7 +155,6 @@ const ButtonWebComponent = forwardRef<View, ButtonProps>(function ButtonWebCompo
   pressed: togglePressed,
   stopPropagation = false,
   appearance: appearanceProp,
-  variant: variantProp,
   tone: toneProp,
   size: sizeProp,
   style,
@@ -180,7 +168,7 @@ const ButtonWebComponent = forwardRef<View, ButtonProps>(function ButtonWebCompo
   renderLeadingIcon,
   renderTrailingIcon,
   iconOnly = false,
-  linkTone = 'primary',
+  linkTone,
   underline,
   textVariant,
   numberOfLines,
@@ -210,25 +198,26 @@ const ButtonWebComponent = forwardRef<View, ButtonProps>(function ButtonWebCompo
   const setRoot = useButtonLayout(ref, onLayout, childRef);
   const hidden = ariaHidden ?? (accessibilityElementsHidden || importantForAccessibility === 'no-hide-descendants' ? true : undefined);
   const theme = useTheme();
+  const layer = useSurfaceLayer();
   const reactId = useId();
   const resolvedId = id ?? `bloom-btn-${reactId}`;
 
-  const recipe = resolveButtonRecipe(variantProp);
-  const appearance = appearanceProp ?? recipe.appearance;
-  const { size, tone } = useBloomAppearance({ size: sizeProp ? BUTTON_SIZE_ALIAS[sizeProp] : undefined, tone: toneProp ?? (variantProp ? recipe.tone : undefined) }, { size: 'md', tone: 'accent' });
+  const appearance = appearanceProp ?? 'solid';
+  useSurfaceRefraction(appearance !== 'plain');
+  const { size, tone } = useBloomAppearance({ size: sizeProp, tone: toneProp }, { size: 'md', tone: 'accent' });
   const geometry = resolveButtonGeometry(size, textVariant);
-  const isSquare = iconOnly || variantProp === 'icon' || sizeProp === 'icon' || (icon != null && children == null);
+  const isSquare = iconOnly || (icon != null && children == null);
   const isIconVariant = isSquare;
-  const isLink = appearance === 'plain' && (href != null || variantProp === 'link');
+  const isLink = appearance === 'plain' && (href != null || linkTone != null);
   const isInteractionBlocked = disabled || loading;
   const longPress = useLongPress(onLongPress, isInteractionBlocked, onPressIn, onPressOut);
   const iconSize = typeof iconSizeProp === 'number' && Number.isFinite(iconSizeProp) && iconSizeProp > 0 ? iconSizeProp : isIconVariant ? ICON_BUTTON_ICON_SIZE[size] : geometry.iconSize;
 
   const palette = useMemo(
-    () => variantProp === 'link' && appearanceProp == null && toneProp == null ? resolveButtonPalette('link', theme, linkTone) : variantProp === 'inverse' && appearanceProp == null && toneProp == null ? resolveButtonPalette('inverse', theme) : resolveButtonPalette(appearance, theme, tone, colors),
-    [appearance, theme, tone, variantProp, appearanceProp, toneProp, linkTone, colors],
+    () => isLink && linkTone != null && toneProp == null ? resolveLinkButtonPalette(theme, linkTone) : resolveButtonPalette(appearance, theme, tone, colors, layer.fill),
+    [appearance, theme, tone, toneProp, isLink, linkTone, colors, layer.fill],
   );
-  const underlineMode = resolveButtonUnderline(isLink ? 'link' : 'primary', underline);
+  const underlineMode = resolveButtonUnderline(isLink, underline);
 
   const containerStyle = useMemo((): CSSProperties => {
     const shadow = palette.shadow ? BUTTON_SHADOW[theme.isDark ? 'dark' : 'light'] : 'none';
@@ -550,52 +539,53 @@ const ButtonWebComponent = forwardRef<View, ButtonProps>(function ButtonWebCompo
 export const Button = memo(ButtonWebComponent);
 Button.displayName = 'Button';
 
-export const PrimaryButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="primary" />
+export const PrimaryButton = memo((props: ButtonProps) => (
+  <Button appearance="solid" tone="accent" {...props} />
 ));
 PrimaryButton.displayName = 'PrimaryButton';
 
-export const SecondaryButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="secondary" />
+export const SecondaryButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} />
 ));
 SecondaryButton.displayName = 'SecondaryButton';
 
-export const IconButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="icon" />
+export const IconButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} iconOnly />
 ));
 IconButton.displayName = 'IconButton';
 
-export const GhostButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="ghost" />
+export const GhostButton = memo((props: ButtonProps) => (
+  <Button appearance="subtle" tone="accent" {...props} />
 ));
 GhostButton.displayName = 'GhostButton';
 
-export const InverseButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="inverse" />
-));
+export const InverseButton = memo((props: ButtonProps) => {
+  const theme = useTheme();
+  return <Button appearance="solid" tone="neutral" colors={props.appearance == null && props.tone == null ? { background: theme.colors.text, foreground: theme.colors.background } : undefined} {...props} />;
+});
 InverseButton.displayName = 'InverseButton';
 
-export const TextButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="text" />
+export const TextButton = memo((props: ButtonProps) => (
+  <Button appearance="plain" tone="accent" {...props} />
 ));
 TextButton.displayName = 'TextButton';
 
-export const OutlineButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="outline" />
+export const OutlineButton = memo((props: ButtonProps) => (
+  <Button appearance="outline" tone="neutral" {...props} />
 ));
 OutlineButton.displayName = 'OutlineButton';
 
 /**
  * `LinkButton`: an inline text action — no fill, no border, the label
- * (plus icons) underlined on hover. `variant` is its colour; pass `href` for an
+ * (plus icons) underlined on hover. `linkTone` is its colour; pass `href` for an
  * anchor.
  */
-export const LinkButton = memo(({ variant = 'primary', ...props }: LinkButtonProps) => (
-  <Button {...props} variant="link" linkTone={variant} />
+export const LinkButton = memo(({ linkTone = 'primary', ...props }: LinkButtonProps) => (
+  <Button appearance="plain" {...props} linkTone={linkTone} />
 ));
 LinkButton.displayName = 'LinkButton';
 
-export const DestructiveButton = memo((props: Omit<ButtonProps, 'variant'>) => (
-  <Button {...props} variant="destructive" />
+export const DestructiveButton = memo((props: ButtonProps) => (
+  <Button appearance="solid" tone="danger" {...props} />
 ));
 DestructiveButton.displayName = 'DestructiveButton';

package/src/button/index.ts

@@ -15,7 +15,6 @@ export { GlyphButton } from './GlyphButton';
 
 export type {
   ButtonProps,
-  ButtonVariant,
   ButtonSize,
   ButtonIconComponent,
   ButtonLinkTone,

package/src/button/index.web.ts

@@ -20,7 +20,6 @@ export { GlyphButton } from './GlyphButton';
 
 export type {
   ButtonProps,
-  ButtonVariant,
   ButtonSize,
   ButtonIconComponent,
   ButtonLinkTone,

package/src/button/shared.ts

@@ -1,4 +1,5 @@
-import { resolveSurfaceFill } from '../surface/shared';
+import { surfaceFillOn } from '../styles/surface-levels';
+import { resolveSurfaceFill, resolveSurfaceTint } from '../surface/shared';
 import { isValidElement, type ReactNode } from 'react';
 
 import { resolveBloomColors } from '../appearance/colors';
@@ -9,7 +10,7 @@ import { parseRgba, withAlpha } from '../theme/color-utils';
 import { TYPE_SCALE, type TypeScaleStyle, type TypeScaleVariant } from '../typography/scale';
 import { oklchToSrgb, srgbToOklch, srgbToRgbString, type Oklch } from '../theme/color-space';
 import type { Theme } from '../theme/types';
-import type { ButtonIconComponent, ButtonSize, ButtonVariant, ButtonLinkTone, ButtonUnderline } from './types';
+import type { ButtonIconComponent, ButtonLinkTone, ButtonUnderline } from './types';
 
 /** Geometry shared by web and native: xs 24, sm 32, md 36, lg 44.
  * Icon actions are squares; native expands compact touch targets with hitSlop.
@@ -301,37 +302,18 @@ export function mixColor(base: string, top: string, alpha: number): string {
 }
 
 /** Shared semantic recipe. Color and fill are independent axes. */
-export const BUTTON_SIZE_ALIAS: Record<ButtonSize, ButtonResolvedSize> = { xs: 'xs', sm: 'sm', md: 'md', lg: 'lg', small: 'sm', medium: 'md', large: 'lg', icon: 'md' };
-
-export function resolveButtonRecipe(variant: ButtonVariant | undefined): { appearance: BloomAppearance; tone: BloomTone } {
-  switch (variant) {
-    case 'secondary': case 'outline': case 'icon': return { appearance: 'outline', tone: 'neutral' };
-    case 'ghost': return { appearance: 'subtle', tone: 'accent' };
-    case 'text': case 'link': return { appearance: 'plain', tone: 'accent' };
-    case 'destructive': return { appearance: 'solid', tone: 'danger' };
-    case 'inverse': return { appearance: 'solid', tone: 'neutral' };
-    default: return { appearance: 'solid', tone: 'accent' };
-  }
-}
-
-/** Legacy variants remain accepted; new appearance/tone are the shared contract. */
-export function resolveButtonPalette(appearance: BloomAppearance | ButtonVariant, theme: Theme, tone: BloomTone | ButtonLinkTone = 'accent', colors?: { background: string; foreground: string }): ButtonPalette {
-  const legacy = !['solid', 'subtle', 'outline', 'plain'].includes(appearance);
-  const recipe = resolveButtonRecipe(legacy ? appearance as ButtonVariant : undefined);
-  const resolvedTone: BloomTone = tone === 'primary' ? 'accent' : tone === 'secondary' || tone === 'text' ? 'neutral' : tone;
-  const palette = resolveCanonicalButtonPalette(legacy ? recipe.appearance : appearance as BloomAppearance, theme, legacy && tone === 'accent' ? recipe.tone : resolvedTone, colors);
-  if (appearance === 'link' && tone === 'text') return { ...palette,
-    rest: { ...palette.rest, foreground: theme.colors.text },
-    hover: { ...palette.hover, foreground: theme.colors.textSecondary, background: 'transparent' },
-    active: { ...palette.active, foreground: theme.colors.textSecondary, background: 'transparent' },
-  };
-  if (appearance === 'link') return { ...palette, hover: { ...palette.hover, foreground: palette.rest.foreground, background: 'transparent' }, active: { ...palette.active, foreground: palette.rest.foreground, background: 'transparent' } };
-  if (appearance === 'inverse') return { ...palette,
-    rest: { ...palette.rest, gradient: null, background: theme.colors.text, foreground: theme.colors.background },
-    hover: { ...palette.hover, gradient: null, background: theme.colors.textSecondary, foreground: theme.colors.background },
-    active: { ...palette.active, gradient: null, background: theme.colors.text, foreground: theme.colors.background },
+/** Resolve the shared appearance/tone contract. */
+export const resolveButtonPalette = resolveCanonicalButtonPalette;
+
+/** Link actions retain their inline foreground and never add hover fill. */
+export function resolveLinkButtonPalette(theme: Theme, tone: ButtonLinkTone): ButtonPalette {
+  const palette = resolveCanonicalButtonPalette('plain', theme, tone === 'primary' ? 'accent' : 'neutral');
+  const foreground = tone === 'primary' ? theme.colors.primary : tone === 'text' ? theme.colors.text : theme.colors.textSecondary;
+  return { ...palette,
+    rest: { ...palette.rest, foreground },
+    hover: { ...palette.hover, foreground: tone === 'text' ? theme.colors.textSecondary : foreground, background: 'transparent' },
+    active: { ...palette.active, foreground: tone === 'text' ? theme.colors.textSecondary : foreground, background: 'transparent' },
   };
-  return palette;
 }
 
 /** Semantic pairs remain authoritative; translucent subtle fills are composited once. */
@@ -340,6 +322,7 @@ export function resolveCanonicalButtonPalette(
   theme: Theme,
   tone: BloomTone = 'accent',
   colors?: { background: string; foreground: string },
+  neutralFill?: string,
 ): ButtonPalette {
   const c = theme.colors;
   const pair = colors ?? resolveBloomColors(c, tone, appearance);
@@ -347,17 +330,22 @@ export function resolveCanonicalButtonPalette(
   const neutral = tone === 'neutral' && !colors;
   const tint = appearance === 'outline' && !colors
     ? resolveBloomColors(c, tone, 'subtle').background : pair.background;
-  const fill = resolveSurfaceFill(tint, false, c.card);
+  const fill = resolveSurfaceFill(tint, c.card);
+  const neutralBase = neutralFill ?? c.card;
+  const neutralHover = neutralFill ? surfaceFillOn(theme, neutralBase) : c.backgroundSecondary;
+  const neutralActive = neutralFill ? surfaceFillOn(theme, neutralHover) : c.backgroundTertiary;
+  const semanticAlpha = colors ? parseRgba(tint)?.a ?? 1 : 1;
   const paint = (state: 0 | 1 | 2): ButtonStatePaint => ({
     background: !surface ? (state ? resolveBloomColors(c, tone, 'subtle').background : 'transparent')
-      : neutral ? [c.card, c.backgroundSecondary, c.backgroundTertiary][state]!
-      : state === 0 ? fill : mixColor(fill, state === 1 ? '#ffffff' : '#000000', state === 1 ? 0.06 : 0.08),
+      : resolveSurfaceTint(neutral ? [neutralBase, neutralHover, neutralActive][state]!
+        : state === 0 ? (colors ? tint : fill)
+        : withAlpha(mixColor(fill, state === 1 ? '#ffffff' : '#000000', state === 1 ? 0.06 : 0.08), semanticAlpha)),
     foreground: neutral ? (appearance === 'plain' && state === 0 ? c.textSecondary : c.text) : pair.foreground,
     border: TRANSPARENT, gradient: null, surface,
   });
   return {
     rest: paint(0), hover: paint(1), active: paint(2),
-    disabled: { background: surface ? resolveSurfaceFill(c.backgroundSecondary, false, c.card) : TRANSPARENT,
+    disabled: { background: surface ? resolveSurfaceTint(neutralHover) : TRANSPARENT,
       foreground: c.textTertiary, border: TRANSPARENT, gradient: null, surface },
     disabledOpacity: 1, borderWidth: appearance === 'outline' ? 1 : 0,
     shadow: surface, ring: tone === 'support' ? c.secondary : tone === 'action' ? c.tertiary : c.primary,
@@ -396,11 +384,11 @@ export function resolveCloseButtonPaint(theme: Theme): CloseButtonPaint {
  * everything else keeps none, unless the caller says otherwise.
  */
 export function resolveButtonUnderline(
-  variant: ButtonVariant,
+  isLink: boolean,
   underline: ButtonUnderline | undefined,
 ): ButtonUnderline {
   if (underline !== undefined) return underline;
-  return variant === 'link' ? 'hover' : 'none';
+  return isLink ? 'hover' : 'none';
 }
 
 // ---------------------------------------------------------------------------

package/src/button/types.ts

@@ -1,79 +1,13 @@
 import type { BloomAppearance, BloomTone, BloomSize } from '../appearance/types';
 import type { BloomIconRenderer } from '../icons/render-icon';
-import type { ComponentType, ReactNode } from 'react';
+import type { ReactNode } from 'react';
 import type { GestureResponderEvent, LayoutChangeEvent, ViewProps, StyleProp, ViewStyle, TextStyle } from 'react-native';
 import type { WebAriaProps } from '../styles/styled-primitives';
 import type { BloomIconComponent } from '../icons/icon-component';
 import type { TypeScaleVariant } from '../typography/scale';
 
-/**
- * Bloom's canonical button variants (shared across native + web) plus the
- * web/shadcn set that DOM apps (auth, console, website) rely on:
- *
- *   - `primary | secondary | inverse | icon | ghost | text` — the original
- *     Bloom set, rendered identically on both platforms.
- *   - `outline | link | destructive` — web additions. They are styled from the
- *     SAME Bloom design tokens so they stay visually consistent with the rest of
- *     the set. On native they fall back to a sensible equivalent
- *     (`outline → secondary`, `link → text`, `destructive → primary` tinted with
- *     the negative token) so passing them never crashes a native consumer.
- *
- * `text` (and its web alias `link`) is DELIBERATELY not a transparent `ghost`:
- * it is the compact inline affordance, so it overrides the size config's padding
- * down to 4/8 on BOTH platforms. `ghost` keeps the full padding — it is a
- * regular button that happens to have no background. The one geometry that does
- * differ by platform is `minHeight`: web clears it for `text`/`link` so the
- * control hugs its label and sits inline, native keeps the size config's value
- * because a finger needs the target and a cursor does not.
- *
- * WHICH ONE IS THE NEUTRAL TRANSPARENT AFFORDANCE — the question five families
- * answered with their own copy before this list said so:
- *
- * - **`ghost` IS NOT TRANSPARENT.** It paints an accent WASH at rest
- *   (`accent-100` / dark `accent-900`) with an accent label. It is the low-
- *   emphasis ACCENT action — the third button in a row that is still part of the
- *   accent family — and it is the wrong control for a neutral ⋯ / × / clear
- *   affordance, which lands tinted. A DESTRUCTIVE action in it is worse: a red
- *   label on a blue wash, which is what `track-list`'s selection bar shipped.
- * - **The neutral transparent ICON button is {@link GlyphButtonProps}**
- *   (`GlyphButton`, beside `Button` in `src/button`): an arbitrary round size, a
- *   neutral glyph, no fill at rest and a neutral wash on hover. Reach for it for
- *   every ⋯, ×, clear, shuffle, repeat and toggle glyph.
- * - `icon` is the neutral icon button WITH A SURFACE (`secondary`'s card +
- *   border) at the fixed 24 / 32 / 36 / 44 heights.
- * - `text` is the transparent LABELLED button: an accent label, a NEUTRAL hover
- *   wash, no fill at rest. Use it where `ghost`'s wash is too loud; colour a
- *   destructive one through `textStyle` plus an `icon` ELEMENT you paint
- *   yourself, or reach for `destructive`.
- * - `link` is running text: no container, no padding, `linkTone` for the colour
- *   and `underline` for whether the underline is the affordance at rest.
- */
-export type ButtonVariant =
-  | 'primary'
-  | 'secondary'
-  | 'inverse'
-  | 'icon'
-  | 'ghost'
-  | 'text'
-  | 'outline'
-  | 'link'
-  | 'destructive';
-
-/**
- * Bloom sizes plus shadcn-style aliases. `sm | md | lg` map onto
- * `small | medium | large`; `icon` maps onto a square icon button at the medium
- * height. The aliases exist so web consumers migrating from shadcn keep their
- * call sites unchanged. `xs` (24px) is the compact tier.
- */
-export type ButtonSize = BloomSize
-  | 'xs'
-  | 'small'
-  | 'medium'
-  | 'large'
-  | 'sm'
-  | 'md'
-  | 'lg'
-  | 'icon';
+/** Shared control size; square geometry is expressed with iconOnly. */
+export type ButtonSize = BloomSize;
 
 export interface ButtonProps {
   onLayout?: (event: LayoutChangeEvent) => void;
@@ -98,7 +32,6 @@ export interface ButtonProps {
   children?: React.ReactNode;
   disabled?: boolean;
 
-  variant?: ButtonVariant;
   size?: ButtonSize;
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
@@ -113,11 +46,10 @@ export interface ButtonProps {
   iconPosition?: 'left' | 'right';
 
   /**
-   * The `link` variant's colour. `primary` is the accent label, `secondary` the
+   * The inline link colour. `primary` is the accent label, `secondary` the
    * secondary-text label, `text` the READING colour (`text` at rest, secondary
    * under a pointer or a press) — the tone an underlined action takes when it
-   * sits inside a sentence and must not read as the accent. Ignored by other
-   * variants.
+   * sits inside a sentence and must not read as the accent. Used by LinkButton and plain inline actions.
    */
   linkTone?: ButtonLinkTone;
 
@@ -125,9 +57,9 @@ export interface ButtonProps {
    * When the label carries its underline. `rest` underlines always — the
    * underline IS the affordance, which is what an inline text action inside
    * running copy needs; `hover` underlines only under a pointer (the `link`
-   * variant's default, and web-only: native has no hover); `none` never does.
+   * action's default, and web-only: native has no hover); `none` never does.
    *
-   * Defaults to `hover` for `link` and `none` for every other variant, so an
+   * Defaults to `hover` for `link` and `none` for other actions, so an
    * existing call site is unchanged. Four families hand-rolled an underlined
    * `Pressable` for exactly this: `stay-filters`, `booking`, `listing-details`
    * and `media-header`.
@@ -307,10 +239,8 @@ export type ButtonLinkTone = 'primary' | 'secondary' | 'text';
 /** When {@link ButtonProps.underline} draws the label's underline. */
 export type ButtonUnderline = 'rest' | 'hover' | 'none';
 
-/** Props of `LinkButton`: its `variant` is the link colour. */
-export interface LinkButtonProps extends Omit<ButtonProps, 'variant' | 'linkTone'> {
-  variant?: ButtonLinkTone;
-}
+/** Inline action with explicit link colour and underline behavior. */
+export type LinkButtonProps = ButtonProps;
 
 /** Props of `CloseButton`. */
 export interface CloseButtonProps {

package/src/button/use-button-layout.web.ts

@@ -9,6 +9,7 @@ function assignRef<T>(ref: Ref<T> | undefined, value: T | null) {
 export function useButtonLayout(ref: Ref<View> | undefined, onLayout?: (event: LayoutChangeEvent) => void, childRef?: Ref<HTMLElement>) {
   const [node, setNode] = useState<HTMLElement | null>(null);
   const callback = useRef(onLayout);
+  const measureAfterCommit = useRef<(() => void) | undefined>(undefined);
   callback.current = onLayout;
   const enabled = Boolean(onLayout);
   const setRef = useCallback((element: HTMLElement | null) => {
@@ -27,12 +28,15 @@ export function useButtonLayout(ref: Ref<View> | undefined, onLayout?: (event: L
       last = key;
       callback.current?.({ nativeEvent: { layout }, target: node, currentTarget: node } as unknown as LayoutChangeEvent);
     };
+    measureAfterCommit.current = measure;
     measure();
     const Resize = node.ownerDocument.defaultView?.ResizeObserver;
     const observer = Resize ? new Resize(measure) : undefined;
     observer?.observe(node);
     node.ownerDocument.defaultView?.addEventListener('resize', measure);
-    return () => { observer?.disconnect(); node.ownerDocument.defaultView?.removeEventListener('resize', measure); };
+    return () => { measureAfterCommit.current = undefined; observer?.disconnect(); node.ownerDocument.defaultView?.removeEventListener('resize', measure); };
   }, [node, enabled]);
+  // A sibling changing width or order moves this button without resizing it.
+  useLayoutEffect(() => { measureAfterCommit.current?.(); });
   return setRef;
 }

package/src/button-group/ButtonGroup.tsx

@@ -1,3 +1,4 @@
+import { Surface } from '../surface';
 import { Button } from '../button';
 import { createButtonGroup } from './ButtonGroupBase';
-export const { ButtonGroup, ButtonGroupItem } = createButtonGroup(Button);
+export const { ButtonGroup, ButtonGroupItem } = createButtonGroup(Button, Surface);

package/src/button-group/ButtonGroup.web.tsx

@@ -1,3 +1,4 @@
+import { Surface } from '../surface/index.web';
 import { Button } from '../button/index.web';
 import { createButtonGroup } from './ButtonGroupBase';
-export const { ButtonGroup, ButtonGroupItem } = createButtonGroup(Button);
+export const { ButtonGroup, ButtonGroupItem } = createButtonGroup(Button, Surface);