@oxy.so/bloom 5.4.1 → 6.0.0

package/src/stay-filters/FilterFooter.tsx

@@ -1,8 +1,8 @@
-import React, { memo, useMemo } from 'react';
+import React, { memo } from 'react';
 import { View } from 'react-native';
 
-import { Button } from '../button';
-import { resolveButtonRamps } from '../button/shared';
+import { Button , LinkButton } from '../button';
+
 import { useTheme } from '../theme/use-theme';
 import { useMessages } from '../locale/messages';
 import { STAY_FILTERS_MESSAGES } from './messages';
@@ -56,11 +56,11 @@ function FilterFooterComponent({
         style,
       ]}
     >
-      <Button
-        variant="link"
+      <LinkButton
+
         linkTone="text"
         underline="rest"
-        size="small"
+        size="sm"
         textVariant="body-semibold"
         style={{ paddingTop: 6, paddingBottom: 6, marginTop: -6, marginBottom: -6 }}
         onPress={onClear}
@@ -68,15 +68,15 @@ function FilterFooterComponent({
         testID={testID ? `${testID}-clear` : undefined}
       >
         {clearLabel}
-      </Button>
+      </LinkButton>
       <Button
-        variant="primary"
-        size="large"
+
+        size="lg"
         onPress={onApply}
         loading={loading}
         disabled={applyDisabled}
         accessibilityLabel={resultsLabel}
-        testID={testID ? `${testID}-apply` : undefined}
+        testID={testID ? `${testID}-apply` : undefined} tone="accent" appearance="solid"
       >
         {resultsLabel}
       </Button>

package/src/stay-filters/FilterTriggerButton.tsx

@@ -1,3 +1,4 @@
+import { useBloomAppearance } from '../appearance';
 import React, { memo } from 'react';
 import { View } from 'react-native';
 
@@ -21,11 +22,14 @@ function FilterTriggerButtonComponent({
   onPress,
   label: labelProp,
   accessibilityLabel,
-  size = 'medium',
+  size: sizeProp,
   disabled,
   style,
   testID,
 }: FilterTriggerButtonProps) {
+  const { size: inheritedSize } = useBloomAppearance({ size: sizeProp }, { size: 'md', tone: 'neutral' });
+  const size = inheritedSize;
+
   const { messages } = useMessages(STAY_FILTERS_MESSAGES);
   const label = labelProp ?? messages.filters;
   const applied = count > 0;
@@ -33,13 +37,13 @@ function FilterTriggerButtonComponent({
 
   const button = (
     <Button
-      variant="outline"
+
       size={size}
       leadingIcon={RiEqualizerLine}
       onPress={onPress}
       disabled={disabled}
       accessibilityLabel={name}
-      testID={testID}
+      testID={testID} tone="neutral" appearance="outline"
     >
       {label}
     </Button>

package/src/stay-filters/SegmentedFilter.tsx

@@ -21,7 +21,7 @@ export function SegmentedFilter<T extends string = string>({
     <SegmentedControl
       label={accessibilityLabel}
       type="radio"
-      size="large"
+      size="lg"
       value={value}
       onChange={onValueChange}
       style={[{ alignSelf: 'stretch' }, style]}

package/src/stay-filters/SwitchFilterRow.tsx

@@ -46,8 +46,8 @@ function SwitchFilterRowComponent({
         )}
       </View>
       <Switch
-        value={value}
-        onValueChange={onValueChange}
+        checked={value}
+        onCheckedChange={onValueChange}
         disabled={disabled}
         accessibilityLabel={name}
         testID={testID}

package/src/stay-filters/types.ts

@@ -197,8 +197,8 @@ export interface FilterTriggerButtonProps {
    * (the badge is a drawn number, so the name has to say it).
    */
   accessibilityLabel?: string;
-  /** `Button` size. Default `medium`. */
-  size?: 'small' | 'medium' | 'large';
+  /** `Button` size. Default `md`. */
+  size?: 'sm' | 'md' | 'lg';
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;

package/src/stay-search/GuestPicker.tsx

@@ -1,8 +1,8 @@
 import React, { memo } from 'react';
 import { View } from 'react-native';
 
-import { Button } from '../button';
-import { resolveButtonRamps } from '../button/shared';
+import { LinkButton } from '../button';
+
 import { StepperRow } from '../stepper';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
@@ -48,7 +48,7 @@ function GuestPickerComponent({
   note,
   onClose,
   closeLabel: closeLabelProp,
-  size = 'medium',
+  size,
   style,
   testID,
 }: GuestPickerProps) {
@@ -102,9 +102,9 @@ function GuestPickerComponent({
       ) : null}
       {close ? (
         <View style={{ alignItems: 'flex-end', paddingTop: 12 }}>
-          <Button variant="link" size="small" onPress={close} testID={testID ? `${testID}-close` : undefined}>
+          <LinkButton  size="sm" onPress={close} testID={testID ? `${testID}-close` : undefined}>
             {closeLabel}
-          </Button>
+          </LinkButton>
         </View>
       ) : null}
     </View>

package/src/stay-search/StaySearchCompact.tsx

@@ -114,14 +114,14 @@ function StaySearchCompactComponent({
       </Pressable>
       {onFilterPress ? (
         <Button
-          variant="secondary"
-          size="medium"
+
+          size="md"
           iconOnly
           icon={filterIcon}
           onPress={onFilterPress}
           accessibilityLabel={filterLabel}
           testID={testID ? `${testID}-filter` : undefined}
-          style={{ marginRight: 9, flexShrink: 0 }}
+          style={{ marginRight: 9, flexShrink: 0 }} tone="neutral" appearance="outline"
         />
       ) : null}
     </View>

package/src/stay-search/types.ts

@@ -169,7 +169,7 @@ export interface GuestPickerProps {
   onClose?: () => void;
   /** `"Close"` in English; follows the locale. */
   closeLabel?: string;
-  /** Stepper size. Default `'medium'`; `'small'` for a popover. */
+  /** Stepper size. Default `'md'`; `'sm'` for a popover. */
   size?: StepperSize;
   style?: StyleProp<ViewStyle>;
   /** Derives `-<kind>` per row (then the stepper's own suffixes). */

package/src/stepper/Stepper.tsx

@@ -1,4 +1,5 @@
-import React, { memo, useCallback, useMemo } from 'react';
+import { useBloomAppearance } from '../appearance';
+import React, { memo, useCallback } from 'react';
 import { Platform, View, type AccessibilityActionEvent } from 'react-native';
 
 import { Button } from '../button';
@@ -51,10 +52,10 @@ const IS_WEB = Platform.OS === 'web';
 
 const SIZE_CONFIG: Record<
   StepperSize,
-  { button: 'small' | 'medium'; type: TypeScaleVariant; valueWidth: number; height: number; gap: number }
+  { button: 'sm' | 'md'; type: TypeScaleVariant; valueWidth: number; height: number; gap: number }
 > = {
-  small: { button: 'small', type: 'body-semibold', valueWidth: 24, height: 32, gap: 8 },
-  medium: { button: 'medium', type: 'headline-semibold', valueWidth: 32, height: 36, gap: 12 },
+  sm: { button: 'sm', type: 'body-semibold', valueWidth: 24, height: 32, gap: 8 },
+  md: { button: 'md', type: 'headline-semibold', valueWidth: 32, height: 36, gap: 12 },
 };
 
 /** Snap to `step` from `min` and clamp, without floating-point drift. */
@@ -90,7 +91,7 @@ function StepperComponent({
   max,
   step = 1,
   disabled: disabledProp = false,
-  size = 'medium',
+  size: sizeProp,
   formatValue,
   accessibilityLabel,
   decrementLabel: decrementLabelProp,
@@ -100,6 +101,8 @@ function StepperComponent({
   style,
   testID,
 }: StepperProps) {
+  const { size: inheritedSize } = useBloomAppearance({ size: sizeProp }, { size: 'md', tone: 'neutral' });
+  const size = inheritedSize === 'xs' || inheritedSize === 'sm' ? 'sm' : 'md';
   const common = useCommonMessages();
   const { messages } = useMessages(STEPPER_MESSAGES);
   const decrementLabel = decrementLabelProp ?? messages.decrease;
@@ -198,7 +201,7 @@ function StepperComponent({
       style={[{ flexDirection: 'row', alignItems: 'center', gap: config.gap }, style]}
     >
       <Button
-        variant="secondary"
+
         size={config.button}
         iconOnly
         icon={removes ? RiDeleteBinLine : RiSubtractLine}
@@ -206,11 +209,13 @@ function StepperComponent({
         disabled={!(canDecrement || removes)}
         accessibilityLabel={removes ? removeLabel : decrementLabel}
         tabIndex={removes ? 0 : -1}
-        testID={testID ? `${testID}-decrement` : undefined}
+        testID={testID ? `${testID}-decrement` : undefined} tone="neutral" appearance="outline"
       />
       <View
         accessibilityRole="adjustable"
         accessibilityLabel={field.accessibilityLabel}
+        aria-describedby={field.describedBy}
+        aria-invalid={field.invalid || undefined}
         aria-valuemin={min}
         aria-valuemax={max}
         aria-valuenow={value}
@@ -236,7 +241,7 @@ function StepperComponent({
         </Text>
       </View>
       <Button
-        variant="secondary"
+
         size={config.button}
         iconOnly
         icon={RiAddLine}
@@ -244,7 +249,7 @@ function StepperComponent({
         disabled={!canIncrement}
         accessibilityLabel={incrementLabel}
         tabIndex={-1}
-        testID={testID ? `${testID}-increment` : undefined}
+        testID={testID ? `${testID}-increment` : undefined} tone="neutral" appearance="outline"
       />
     </View>
   );

package/src/stepper/types.ts

@@ -1,8 +1,8 @@
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
-/** `small` pairs 32px buttons with body text; `medium` (default) 38px buttons with headline text. */
-export type StepperSize = 'small' | 'medium';
+/** `sm` pairs 32px buttons with body text; `md` (default) 36px buttons with headline text. */
+export type StepperSize = 'sm' | 'md';
 
 export interface StepperProps {
   /** The current value. The stepper is fully controlled. */
@@ -17,7 +17,7 @@ export interface StepperProps {
   step?: number;
   /** Disables both buttons and the keyboard. */
   disabled?: boolean;
-  /** Default `medium`. */
+  /** Default `md`. */
   size?: StepperSize;
   /** How the value is drawn and announced (`aria-valuetext`), e.g. `(n) => \`${n}+\``. */
   formatValue?: (value: number) => string;

package/src/styles/surface-levels.ts

@@ -103,6 +103,7 @@ import { Platform, type ViewStyle } from 'react-native';
 
 import type { Theme } from '../theme/types';
 import { useTheme } from '../theme/use-theme';
+import { BloomThemeContext } from '../theme/BloomThemeProvider';
 import { mixColors, quietText } from './color-contrast';
 import { RING_OFFSET_VAR } from './interactive-web-css';
 import type { WebCssStyle } from './web-view-style';
@@ -360,6 +361,13 @@ export function useSurfaceLevel(delta: number = 0): SurfaceLevelPaint {
  * app does not repeat a guess at every call site and does not have to be swept
  * when a container changes what it paints.
  */
+/** Optional ambient fill for layout containers that also work without a theme. */
+export function useOptionalSurfaceFill(): string | undefined {
+  const theme = useContext(BloomThemeContext)?.theme;
+  const { level, fill } = useContext(SurfaceLevelContext);
+  return fill ?? (theme ? levelBackground(theme, level) : undefined);
+}
+
 export function useSurfaceFill(): string {
   const theme = useTheme();
   const { level, fill } = useContext(SurfaceLevelContext);

package/src/surface/Surface.tsx

@@ -1,30 +1,25 @@
-import { surfaceStyle } from '../shapes/surface-style';
+import { resolveSurfaceGeometry } from './resolve-surface-geometry';
 import { SURFACE_SHAPES } from '../design-tokens/shapes';
 import React, { forwardRef, memo } from 'react';
 import { styled } from 'react-native-css';
 import { Platform, StyleSheet, type View } from 'react-native';
-import { parseRgba, withAlpha } from '../theme/color-utils';
 import { StyledView } from '../styles/styled-primitives';
 import { borderRadius } from '../styles/tokens';
-import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
-import { useSurfaceLayer } from './use-surface-layer';
-import { resolveSurfaceFill } from './shared';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
+import { useResolvedSurface } from './use-resolved-surface';
 import { SurfacePaint } from './SurfacePaint';
 import type { SurfaceProps } from './types';
 
 /** Layout-neutral container: callers supply their own padding and content. */
 const SurfaceComponent = forwardRef<View, SurfaceProps>(function SurfaceComponent({
-  children, material = 'solid', fill, radius = borderRadius.xl, cornerCurve = SURFACE_SHAPES.panel.curve,
+  children, fill, radius, cornerCurve = SURFACE_SHAPES.panel.curve,
   style, className, accessibilityLabel, testID, ...hostProps
 }, ref) {
-  const glass = material === 'glass';
-  const layer = useSurfaceLayer();
   const resolvedStyle = StyleSheet.flatten(style);
-  const effectiveRadius = resolvedStyle?.borderRadius ?? radius;
-  const tint = fill ?? resolvedStyle?.backgroundColor ?? (glass ? withAlpha(layer.fill, 0.25) : layer.fill);
-  const painted = glass || (tint !== 'transparent' && parseRgba(String(tint))?.a !== 0);
-  const color = resolveSurfaceFill(String(tint), glass, layer.parentFill);
-  const publishedFill = painted ? resolveSurfaceFill(color, false, layer.parentFill) : layer.parentFill;
+  const geometry = resolveSurfaceGeometry(radius, style, borderRadius.xl, cornerCurve);
+
+  const override = fill ?? resolvedStyle?.backgroundColor;
+  const material = useResolvedSurface({ fill: override === undefined ? undefined : String(override) });
   return (
     <StyledView
       {...hostProps}
@@ -32,10 +27,10 @@ const SurfaceComponent = forwardRef<View, SurfaceProps>(function SurfaceComponen
       className={className}
       accessibilityLabel={accessibilityLabel}
       testID={testID}
-      style={[{ position: 'relative', borderRadius: effectiveRadius, ...surfaceStyle({ curve: cornerCurve }) }, style, { backgroundColor: 'transparent', ...surfaceFillVars(painted ? publishedFill : undefined) }]}
+      style={[{ position: 'relative' }, style, { backgroundColor: 'transparent', ...material.vars, ...geometry.style }]}
     >
-      {painted ? <SurfacePaint fill={color} backdrop={layer.parentFill} radius={effectiveRadius} shape={{ curve: cornerCurve }} glass={glass} /> : null}
-      <SurfaceLevelProvider level={painted ? layer.level : layer.parentLevel} fill={publishedFill}>{children}</SurfaceLevelProvider>
+      {material.painted ? <SurfacePaint fill={material.paintFill} radius={geometry.radius} shape={geometry.shape} /> : null}
+      <SurfaceLevelProvider level={material.level} fill={material.publishedFill}>{children}</SurfaceLevelProvider>
     </StyledView>
   );
 });

package/src/surface/Surface.web.tsx

@@ -1,16 +1,15 @@
-import { surfaceStyle } from '../shapes/surface-style';
+import { resolveSurfaceGeometry } from './resolve-surface-geometry';
 import { SURFACE_SHAPES } from '../design-tokens/shapes';
 import React, { forwardRef, memo } from 'react';
 import { StyleSheet, type View } from 'react-native';
-import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
-import { useSurfaceLayer } from './use-surface-layer';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
+import { useResolvedSurface } from './use-resolved-surface';
 import { useTheme } from '../theme/use-theme';
-import { parseRgba, withAlpha } from '../theme/color-utils';
 import { borderRadius } from '../styles/tokens';
 import { StyledView } from '../styles/styled-primitives';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { useInteractiveWebCss } from '../styles/interactive-web-css';
-import { resolveSurfaceFill, resolveSurfaceOptics } from './shared';
+import { resolveSurfaceOptics } from './shared';
 import { surfaceMaterialCss } from './web-material';
 import { useSurfaceRefraction } from './web-refraction';
 import type { SurfaceProps } from './types';
@@ -22,43 +21,38 @@ const CSS = `
   box-sizing: border-box;
 }
 .bloom-surface { overflow: hidden; }
-${surfaceMaterialCss('.bloom-surface--solid', 'var(--bloom-surface-fill)')}
-${surfaceMaterialCss('.bloom-surface--glass', 'var(--bloom-surface-fill)', 'none', true)}
+${surfaceMaterialCss('.bloom-surface--material', 'var(--bloom-surface-fill)')}
 `;
 
 const SurfaceComponent = forwardRef<View, SurfaceProps>(function SurfaceComponent({
-  children, material = 'solid', fill, radius = borderRadius.xl, cornerCurve = SURFACE_SHAPES.panel.curve,
+  children, fill, radius, cornerCurve = SURFACE_SHAPES.panel.curve,
   style, className, accessibilityLabel, testID, ...hostProps
 }, ref) {
   const theme = useTheme();
-  const glass = material === 'glass';
-  const layer = useSurfaceLayer();
   const resolvedStyle = StyleSheet.flatten(style);
+  const geometry = resolveSurfaceGeometry(radius, style, borderRadius.xl, cornerCurve);
   useInteractiveWebCss('bloom-surface-web-css', CSS);
-  useSurfaceRefraction(glass);
-  const tint = fill ?? resolvedStyle?.backgroundColor ?? (glass ? withAlpha(layer.fill, 0.25) : layer.fill);
-  const painted = glass || (tint !== 'transparent' && parseRgba(String(tint))?.a !== 0);
-  const color = resolveSurfaceFill(String(tint), glass, layer.parentFill);
-  const publishedFill = painted ? resolveSurfaceFill(color, false, layer.parentFill) : layer.parentFill;
+  const override = fill ?? resolvedStyle?.backgroundColor;
+  const material = useResolvedSurface({ fill: override === undefined ? undefined : String(override) });
+  useSurfaceRefraction(material.painted);
   const optics = resolveSurfaceOptics(theme.isDark);
   const baseStyle: WebCssStyle = {
     '--bloom-surface-rim': optics.rim,
     '--bloom-surface-sheen': optics.sheenCss,
-    borderRadius: radius,
-    ...surfaceStyle({ curve: cornerCurve }),
+    ...geometry.style,
     backgroundColor: 'transparent',
-    '--bloom-surface-fill': color,
+    '--bloom-surface-fill': material.paintFill,
   };
   return (
     <StyledView
       {...hostProps}
       ref={ref}
-      className={['bloom-surface', painted ? glass ? 'bloom-surface--glass' : 'bloom-surface--solid' : '', className].filter(Boolean).join(' ')}
+      className={['bloom-surface', material.painted ? 'bloom-surface--material' : '', className].filter(Boolean).join(' ')}
       accessibilityLabel={accessibilityLabel}
       testID={testID}
-      style={[baseStyle, style, { backgroundColor: 'transparent', ...surfaceFillVars(painted ? publishedFill : undefined) }]}
+      style={[baseStyle, style, { backgroundColor: 'transparent', ...material.vars, ...geometry.style }]}
     >
-      <SurfaceLevelProvider level={painted ? layer.level : layer.parentLevel} fill={publishedFill}>{children}</SurfaceLevelProvider>
+      <SurfaceLevelProvider level={material.level} fill={material.publishedFill}>{children}</SurfaceLevelProvider>
     </StyledView>
   );
 });

package/src/surface/SurfacePaint.tsx

@@ -10,12 +10,11 @@ import type { WebCssStyle } from '../styles/web-view-style';
 import { surfaceMaterialCss } from './web-material';
 import { useSurfaceRefraction } from './web-refraction';
 import { useTheme } from '../theme/use-theme';
-import { resolveSurfaceFill, resolveSurfaceOptics, surfaceSvgStop } from './shared';
+import { resolveSurfaceTint, resolveSurfaceOptics, surfaceSvgStop } from './shared';
 
 const WEB_PAINT_CSS = `
 .bloom-surface-paint { isolation: isolate; overflow: hidden; }
-${surfaceMaterialCss('.bloom-surface-paint--solid', 'var(--bloom-surface-paint-fill)')}
-${surfaceMaterialCss('.bloom-surface-paint--glass', 'var(--bloom-surface-paint-fill)', 'none', true)}
+${surfaceMaterialCss('.bloom-surface-paint', 'var(--bloom-surface-paint-fill)')}
 .bloom-surface-paint--no-sheen::after { background-image: none; }
 `;
 
@@ -27,21 +26,16 @@ ${surfaceMaterialCss('.bloom-surface-paint--glass', 'var(--bloom-surface-paint-f
  */
 export const SurfacePaint = memo(function SurfacePaint({
   fill,
-  backdrop,
   radius,
   shape,
   direction = 'ltr',
-  glass = false,
   sheen = true,
   testID,
 }: {
-  glass?: boolean;
   sheen?: boolean;
   testID?: string;
   /** Omit for sheen/rim only on a host that already owns its fill. */
   fill?: string;
-  /** Actual parent fill when compositing a solid material. */
-  backdrop?: string;
   radius?: NonNullable<ViewStyle['borderRadius']>;
   /** Same policy as the host; radius can remain owned by an animated host. */
   shape?: SurfaceShape;
@@ -50,10 +44,10 @@ export const SurfacePaint = memo(function SurfacePaint({
   const geometry = { ...(radius === undefined ? {} : { borderRadius: radius }), ...surfaceStyle(shape ?? { curve: 'round' }, direction) };
   const theme = useTheme();
   const optics = resolveSurfaceOptics(theme.isDark);
-  const resolvedFill = fill === undefined ? 'transparent' : resolveSurfaceFill(fill, glass, backdrop ?? theme.colors.card);
+  const resolvedFill = resolveSurfaceTint(fill ?? 'transparent');
   const id = useSvgIdPrefix('bloom-surface');
   const isWeb = Platform.OS === 'web';
-  useSurfaceRefraction(isWeb && glass);
+  useSurfaceRefraction(isWeb);
   useEffect(() => {
     if (isWeb) adoptStyleSheet('bloom-surface-paint-web-css', WEB_PAINT_CSS);
   }, [isWeb]);
@@ -67,7 +61,7 @@ export const SurfacePaint = memo(function SurfacePaint({
       '--bloom-surface-rim': optics.rim,
       '--bloom-surface-sheen': optics.sheenCss,
     };
-    return <StyledView testID={testID} pointerEvents="none" className={`${glass ? 'bloom-surface-paint bloom-surface-paint--glass' : 'bloom-surface-paint bloom-surface-paint--solid'}${sheen ? '' : ' bloom-surface-paint--no-sheen'}`} style={paintStyle} />;
+    return <StyledView testID={testID} pointerEvents="none" className={`bloom-surface-paint${sheen ? '' : ' bloom-surface-paint--no-sheen'}`} style={paintStyle} />;
   }
   const base = surfaceSvgStop(resolvedFill);
   return (
@@ -89,4 +83,3 @@ export const SurfacePaint = memo(function SurfacePaint({
     </View>
   );
 });
-

package/src/surface/resolve-surface-geometry.ts

@@ -0,0 +1,18 @@
+import { StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { surfaceStyle } from '../shapes/surface-style';
+import type { CornerCurve, SurfaceShape } from '../shapes/corner-types';
+
+/** Explicit axis > resolved caller style/class > family default, on both paint and host. */
+export function resolveSurfaceGeometry(
+  radius: ViewStyle['borderRadius'] | undefined,
+  style: StyleProp<ViewStyle> | undefined,
+  fallback: number,
+  curve: CornerCurve,
+) {
+  const effectiveRadius = radius ?? StyleSheet.flatten(style)?.borderRadius ?? fallback;
+  const shape: SurfaceShape = {
+    ...(typeof effectiveRadius === 'number' ? { radius: effectiveRadius } : {}),
+    curve: effectiveRadius === 9999 ? 'round' : curve,
+  };
+  return { radius: effectiveRadius, shape, style: { ...surfaceStyle(shape), borderRadius: effectiveRadius } };
+}

package/src/surface/resolve-surface-material.ts

@@ -0,0 +1,28 @@
+import { parseRgba } from '../theme/color-utils';
+import { surfaceFillVars, type SurfaceLevel } from '../styles/surface-levels';
+import { resolveSurfaceFill, resolveSurfaceTint } from './shared';
+
+export interface SurfaceMaterialInput {
+  fill: string;
+  parentFill: string;
+  parentLevel?: SurfaceLevel;
+  /** False for plain/backing hosts: publish their fill without material or a depth step. */
+  paint?: boolean;
+  /** Explicit depth origin for portals, rather than inheriting the triggering card. */
+  level?: SurfaceLevel;
+}
+
+/** One decision for the pixels, descendant backing, depth and CSS aliases. */
+export function resolveSurfaceMaterial({ fill, parentFill, parentLevel = 0, paint = true, level }: SurfaceMaterialInput) {
+  const visible = fill.trim().toLowerCase() !== 'transparent' && parseRgba(fill)?.a !== 0;
+  const painted = paint && visible;
+  const paintFill = painted ? resolveSurfaceTint(fill) : fill;
+  const publishedFill = resolveSurfaceFill(paintFill, parentFill);
+  return {
+    painted,
+    paintFill,
+    publishedFill,
+    level: level ?? (painted ? Math.min(parentLevel + 1, 3) as SurfaceLevel : parentLevel),
+    vars: surfaceFillVars(visible ? publishedFill : undefined),
+  };
+}

package/src/surface/shared.ts

@@ -36,9 +36,14 @@ export function surfaceSvgStop(color: string): { color: string; opacity: number
 }
 
 
-/** Solid material flattens a translucent tint onto its resolved backing. */
-export function resolveSurfaceFill(fill: string, glass: boolean, backdrop: string): string {
-  if (glass) return fill;
+/** One subtle material: retain explicit alpha; opaque fills transmit ten percent. */
+export function resolveSurfaceTint(fill: string): string {
+  const parsed = parseRgba(fill);
+  return parsed?.a === 1 ? withAlpha(fill, 0.9) : fill;
+}
+
+/** Estimate the backing descendants see by compositing tint onto its parent. */
+export function resolveSurfaceFill(fill: string, backdrop: string): string {
   if (fill.trim().toLowerCase() === 'transparent') return backdrop;
   const tint = parseRgba(fill);
   const base = parseRgba(backdrop);

package/src/surface/types.ts

@@ -4,11 +4,9 @@ import type { StyleProp, ViewStyle, ViewProps } from 'react-native';
 
 export interface SurfaceProps extends Omit<ViewProps, 'style' | 'children'> {
   children?: ReactNode;
-  /** Solid (default) keeps the gradient and rim on an opaque fill; glass adds transparency and web refraction. */
-  material?: 'glass' | 'solid';
-  /** Explicit tint. Defaults to a surface above the actual parent. Solid composites alpha onto that parent; glass preserves it. */
+  /** Tint source. Opaque colours use 90% opacity; supplied alpha is preserved. */
   fill?: string;
-  /** Radius shared by the layout box and its clipped paint. Defaults to 20. */
+  /** Radius shared by host and paint. Explicit prop wins over style.borderRadius, then default 20. */
   radius?: number;
   /** Platform-adaptive corners shared by the host and material. */
   cornerCurve?: CornerCurve;

package/src/surface/use-resolved-surface.ts

@@ -0,0 +1,8 @@
+import { useSurfaceLayer } from './use-surface-layer';
+import { resolveSurfaceMaterial, type SurfaceMaterialInput } from './resolve-surface-material';
+
+/** Passive surface defaults come from the actual nearest backing. */
+export function useResolvedSurface(options: Partial<SurfaceMaterialInput> = {}) {
+  const parent = useSurfaceLayer();
+  return resolveSurfaceMaterial({ ...options, fill: options.fill ?? parent.fill, parentFill: options.parentFill ?? parent.parentFill, parentLevel: options.parentLevel ?? parent.parentLevel });
+}

package/src/surface/use-surface-backing.ts

@@ -1,14 +1,12 @@
 import { StyleSheet, type ColorValue, type StyleProp, type ViewStyle } from 'react-native';
-import { useSurfaceFill, useSurfaceLevelValue, surfaceFillVars } from '../styles/surface-levels';
-import { parseRgba } from '../theme/color-utils';
-import { resolveSurfaceFill } from './shared';
+import { useSurfaceFill, useSurfaceLevelValue } from '../styles/surface-levels';
+import { resolveSurfaceMaterial } from './resolve-surface-material';
 
 /** Docked chrome publishes its backing without adding depth or material. */
 export function useSurfaceBacking(defaultFill: ColorValue | undefined, style?: StyleProp<ViewStyle>, known = true) {
   const parentFill = useSurfaceFill();
   const level = useSurfaceLevelValue();
   const background = known ? StyleSheet.flatten(style)?.backgroundColor ?? defaultFill : undefined;
-  const painted = typeof background === 'string' && background !== 'transparent' && parseRgba(background)?.a !== 0;
-  const fill = painted ? resolveSurfaceFill(background, false, parentFill) : parentFill;
-  return { fill, level, vars: surfaceFillVars(painted ? fill : undefined) };
+  const material = resolveSurfaceMaterial({ fill: typeof background === 'string' ? background : 'transparent', parentFill, parentLevel: level, paint: false });
+  return { fill: material.publishedFill, level: material.level, vars: material.vars };
 }

package/src/surface/use-surface-material.web.ts

@@ -1,18 +1,22 @@
+import { useSurfaceRefraction } from './web-refraction';
 import { useContext, useMemo } from 'react';
 import { BloomThemeContext } from '../theme/BloomThemeProvider';
 import { useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
-import { resolveSurfaceOptics } from './shared';
+import { resolveSurfaceOptics, resolveSurfaceTint } from './shared';
 import { surfaceMaterialCss } from './web-material';
 
-/** Decorate an existing web host; preserve its fill, radius, layout and shadow. */
-export function useSurfaceMaterial(selector: string, id: string): WebCssStyle {
-  const css = useMemo(() => `${selector} { isolation: isolate; }\n${surfaceMaterialCss(selector, 'transparent')}`, [selector]);
+/** Move a web host fill into the shared body and edge paint; preserve layout and shadow. */
+export function useSurfaceMaterial(selector: string, id: string, fill: string): WebCssStyle {
+  useSurfaceRefraction(true);
+  const css = useMemo(() => `${selector} { isolation: isolate; }\n${surfaceMaterialCss(selector, 'var(--bloom-surface-fill)')}`, [selector]);
   useInteractiveWebCss(id, css);
   const theme = useContext(BloomThemeContext)?.theme;
   const optics = resolveSurfaceOptics(theme?.isDark ?? false);
   return useMemo(() => ({
+    backgroundColor: 'transparent',
+    '--bloom-surface-fill': resolveSurfaceTint(fill),
     '--bloom-surface-rim': optics.rim,
     '--bloom-surface-sheen': optics.sheenCss,
-  }), [optics]);
+  }), [optics, fill]);
 }