@oxy.so/bloom 5.4.0 → 6.0.0

package/scripts/migrations/unify-bloom-api.mjs

@@ -0,0 +1,201 @@
+/** Import-aware migration. Defaults to preview; --write applies safe literal edits.
+ * Dynamic variants/spreads are reported for review, never guessed.
+ * Usage: node scripts/migrations/unify-bloom-api.mjs --write src templates docs
+ */
+import ts from 'typescript';
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const buttonKinds = new Set(['Button', 'PrimaryButton', 'SecondaryButton', 'IconButton', 'GhostButton', 'TextButton', 'InverseButton', 'OutlineButton', 'LinkButton', 'DestructiveButton', 'CloseButton']);
+const buttonVariants = {
+  primary: ['solid', 'accent'], secondary: ['outline', 'neutral'], outline: ['outline', 'neutral'],
+  icon: ['outline', 'neutral'], ghost: ['subtle', 'accent'], text: ['plain', 'accent'], destructive: ['solid', 'danger'],
+};
+const cardVariants = { plain: 'solid', elevated: 'solid', outlined: 'outline', filled: 'subtle' };
+const sizes = { small: 'sm', medium: 'md', large: 'lg', default: 'md', icon: 'md' };
+
+export function migrateSource(source, filename = 'consumer.tsx', snippets = false, internal = false) {
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const edits = []; const warnings = []; const bindings = new Map(); const additions = new Map();
+  const edit = (start, end, text) => {
+    if (text === '') {
+      const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+      const lineEnd = source.indexOf('\n', end);
+      if (lineEnd >= 0 && !source.slice(lineStart, start).trim() && !source.slice(end, lineEnd).trim()) {
+        start = lineStart; end = lineEnd + 1;
+      }
+    }
+    edits.push({start, end, text});
+  };
+  const warn = (node, reason) => warnings.push({line: file.getLineAndCharacterOfPosition(node.getStart(file)).line + 1, reason});
+  const recognized = name => buttonKinds.has(name) || ['Card', 'Switch', 'ControlSurface', 'TextField', 'TextFieldInput', 'Textarea', 'TimeField', 'Select', 'SelectTrigger', 'Checkbox', 'ButtonGroup', 'ButtonGroupItem', 'Stepper', 'FollowButton', 'FilterTriggerButton', 'NoteEditor', 'NoteEditorToolbar', 'TagField', 'Radio', 'RadioGroup', 'RadioCard', 'Loading', 'InputGroup', 'SegmentedControl', 'Fab', 'CallControl', 'RatingInput', 'PlayButton', 'LikeButton', 'ReactionPicker', 'TransportControls', 'PlaybackSpeedMenu', 'SleepTimerMenu'].includes(name);
+  const isBloom = module => /^@oxy\.so\/bloom(?:\/|$)/.test(module) || (internal && /^(?:\.\.?\/)+(?:.*\/)?(?:button|card|switch|control-surface|text-field|textarea|time-field|select|checkbox|button-group|stepper|media-header|stay-filters|note-editor|tag-field|date-picker|radio|loading|input-group|segmented-control|fab|call-ui|rating|media-controls|chat-composer|media-player)(?:\/.*)?$/.test(module));
+  for (const statement of file.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const module = statement.moduleSpecifier.text;
+    if (!isBloom(module)) continue;
+    const imports = statement.importClause?.namedBindings;
+    if (imports && ts.isNamespaceImport(imports)) warn(statement, 'Namespace import: review component props manually');
+    if (module.includes('control-surface') && imports && ts.isNamedImports(imports) && imports.elements.some(item => (item.propertyName ?? item.name).text !== 'ControlSurface')) {
+      warn(statement, 'ControlSurface hook/type imports need manual migration to the appearance contract');
+      continue;
+    }
+    if (imports && ts.isNamedImports(imports)) for (const specifier of imports.elements) {
+      const imported = (specifier.propertyName ?? specifier.name).text;
+      if (!recognized(imported)) continue;
+      bindings.set(specifier.name.text, { imported, module, imports, specifier, statement });
+    }
+  }
+  const declaredNames = new Set();
+  const collectName = name => {
+    if (!name) return;
+    if (ts.isIdentifier(name)) declaredNames.add(name.text);
+    else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) for (const item of name.elements) if (ts.isBindingElement(item)) collectName(item.name);
+  };
+  const collect = node => {
+    if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) || ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isParameter(node)) collectName(node.name);
+    ts.forEachChild(node, collect);
+  };
+  collect(file);
+  const bindingFor = name => bindings.get(name) ?? (snippets && !declaredNames.has(name) && recognized(name) ? {imported: name} : undefined);
+  const requireName = (name, binding) => {
+    for (const [local, existing] of bindings) if (existing.imported === name) return local;
+    if (!binding.imports) return name;
+    const key = binding.imports;
+    const names = additions.get(key) ?? new Set();
+    // Avoid shadowing an unrelated import/local declaration.
+    if (declaredNames.has(name)) return null;
+    names.add(name); additions.set(key, names);
+    return name;
+  };
+  const visit = node => {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tag = node.tagName.getText(file); const binding = bindingFor(tag);
+      if (binding) {
+        const kind = binding.imported;
+        const attrs = new Map(node.attributes.properties.filter(ts.isJsxAttribute).map(a => [a.name.getText(file), a]));
+        const getValue = attr => {
+          if (!attr?.initializer) return undefined;
+          const i = attr.initializer;
+          if (ts.isStringLiteral(i)) return i.text;
+          if (ts.isJsxExpression(i) && i.expression && ts.isStringLiteral(i.expression)) return i.expression.text;
+          return undefined;
+        };
+        const add = (name, value) => { if (!attrs.has(name)) edit(node.attributes.end, node.attributes.end, ` ${name}${value === true ? '' : `="${value}"`}`); };
+        const rename = newName => {
+          const local = requireName(newName, binding);
+          if (!local) { warn(node, `Name ${newName} is already used; migrate this element manually`); return false; }
+          edit(node.tagName.getStart(file), node.tagName.end, local);
+          if (ts.isJsxOpeningElement(node) && ts.isJsxElement(node.parent)) edit(node.parent.closingElement.tagName.getStart(file), node.parent.closingElement.tagName.end, local);
+          return true;
+        };
+        const variant = attrs.get('variant'); const value = getValue(variant);
+        if (variant && node.attributes.properties.some(ts.isJsxSpreadAttribute)) {
+          warn(variant, 'A spread may supply appearance/tone; migrate the variant with explicit precedence');
+          ts.forEachChild(node, visit); return;
+        }
+        if (buttonKinds.has(kind) && kind !== 'LinkButton' && (value === 'inverse' || value === 'link') && (attrs.has('appearance') || attrs.has('tone') || attrs.has('colors'))) {
+          warn(variant, 'Link/inverse with explicit visual axes requires semantic review');
+          ts.forEachChild(node, visit); return;
+        }
+        if ((buttonKinds.has(kind) || kind === 'Card') && variant) {
+          if (value === undefined) warn(variant, `${kind} dynamic variant requires semantic migration`);
+          else if (kind === 'LinkButton') edit(variant.name.getStart(file), variant.name.end, 'linkTone');
+          else if (kind === 'Card' && cardVariants[value]) {
+            edit(variant.getStart(file), variant.end, ''); add('appearance', cardVariants[value]);
+            if (value === 'plain' && !attrs.has('appearance')) add('elevation', 'none');
+          } else if (buttonKinds.has(kind) && (value === 'inverse' || value === 'link')) {
+            if (rename(value === 'inverse' ? 'InverseButton' : 'LinkButton')) edit(variant.getStart(file), variant.end, '');
+          } else if (buttonKinds.has(kind) && buttonVariants[value]) {
+            edit(variant.getStart(file), variant.end, ''); add('appearance', buttonVariants[value][0]); add('tone', buttonVariants[value][1]);
+            if (value === 'icon') add('iconOnly', true);
+          } else warn(variant, `Unknown ${kind} variant ${value}`);
+        }
+        if (kind === 'Fab') {
+          for (const old of ['placement', 'offset', 'zIndex', 'minimizeBehavior', 'children']) if (attrs.has(old)) warn(attrs.get(old), `Fab ${old} must move to its Screen/BottomBar parent or explicit collapsed state`);
+          if (variant) {
+            const tones = {primary:'accent', secondary:'support', tertiary:'action', surface:'neutral'};
+            if (tones[value]) { edit(variant.getStart(file), variant.end, ''); add('tone', tones[value]); add('appearance', value === 'surface' ? 'subtle' : 'solid'); }
+            else warn(variant, 'Dynamic Fab variant requires semantic migration');
+          }
+        }
+        const size = attrs.get('size'); const sizeValue = getValue(size);
+        if (kind === 'Fab' && size && sizeValue === undefined) warn(size, 'Fab size must be a canonical preset; migrate numeric/dynamic geometry explicitly');
+        const mappedSize = kind === 'Fab' && sizeValue === 'small' ? 'xs' :
+          ['TransportControls', 'PlaybackSpeedMenu', 'SleepTimerMenu'].includes(kind) ? ({compact:'sm',regular:'md',large:'lg'}[sizeValue] ?? sizes[sizeValue]) : sizes[sizeValue];
+        if (mappedSize) {
+          edit(size.initializer.getStart(file), size.initializer.end, `"${mappedSize}"`);
+          if (sizeValue === 'icon') add('iconOnly', true);
+        }
+        if (kind === 'Switch' || ['Radio', 'RadioGroup', 'RadioCard'].includes(kind)) for (const [old, replacement] of (kind === 'Switch' ? [['value','checked'], ['onValueChange','onCheckedChange']] : [['selected','checked'], ['onSelect','onValueChange']])) {
+          const attr = attrs.get(old);
+          if (attr) {
+            if (attrs.has(replacement)) edit(attr.getStart(file), attr.end, '');
+            else edit(attr.name.getStart(file), attr.name.end, replacement);
+          }
+        }
+        if (kind === 'ControlSurface') {
+          const density = attrs.get('density');
+          if (density) {
+            edit(density.name.getStart(file), density.name.end, 'size');
+            const v = getValue(density);
+            if (sizes[v]) edit(density.initializer.getStart(file), density.initializer.end, `"${sizes[v]}"`);
+            else if (v === undefined) warn(density, 'Dynamic density: migrate values to xs/sm/md/lg');
+          }
+          if (tag === 'ControlSurface') {
+            edit(node.tagName.getStart(file), node.tagName.end, 'BloomScope');
+            if (ts.isJsxOpeningElement(node) && ts.isJsxElement(node.parent)) edit(node.parent.closingElement.tagName.getStart(file), node.parent.closingElement.tagName.end, 'BloomScope');
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  for (const [local, binding] of bindings) if (binding.imported === 'ControlSurface') {
+    edit(binding.specifier.getStart(file), binding.specifier.end, local === 'ControlSurface' ? 'BloomScope' : `BloomScope as ${local}`);
+    if (binding.module.includes('control-surface')) edit(binding.statement.moduleSpecifier.getStart(file), binding.statement.moduleSpecifier.end, JSON.stringify(binding.module.replace(/control-surface(?:\/.*)?$/, 'appearance')));
+  }
+  for (const [imports, names] of additions) {
+    // The closing brace is stable even with a trailing comma.
+    const last = imports.elements.at(-1); const trailing = last && source.slice(last.end, imports.end - 1).includes(',');
+    edit(imports.end - 1, imports.end - 1, `${last && !trailing ? ',' : ''} ${[...names].join(', ')} `);
+  }
+  const unique = [...new Map(edits.map(e => [`${e.start}:${e.end}:${e.text}`, e])).values()];
+  unique.sort((a,b) => b.start - a.start || b.end - a.end);
+  let output = source;
+  for (const e of unique) output = output.slice(0,e.start) + e.text + output.slice(e.end);
+  return {source: output, warnings};
+}
+
+function migrateFile(source, filename, internal) {
+  if (!filename.endsWith('.mdx') && !filename.endsWith('.md')) return migrateSource(source, filename, false, internal);
+  const warnings = [];
+  const output = source.replace(/```(?:tsx|jsx|typescript|ts)\n([\s\S]*?)```/g, (block, code, offset) => {
+    const result = migrateSource(code, filename, internal, internal);
+    warnings.push(...result.warnings.map(w => ({...w, line: w.line + source.slice(0,offset).split('\n').length})));
+    return block.replace(code, result.source);
+  });
+  return {source: output, warnings};
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const args = process.argv.slice(2); const write = args.includes('--write'); const internal = args.includes('--internal');
+  const exclude = args.find(a => a.startsWith('--exclude='))?.slice(10).split(',') ?? [];
+  const roots = args.filter(a => !a.startsWith('--'));
+  if (!roots.length) { console.error('Usage: node scripts/migrations/unify-bloom-api.mjs [--write] [--internal] [--exclude=path,...] <paths...>'); process.exit(1); }
+  let changed = 0, pending = 0;
+  const walk = path => {
+    if (exclude.some(prefix => resolve(path).startsWith(resolve(prefix)))) return;
+    if (statSync(path).isDirectory()) {
+      for (const entry of readdirSync(path)) if (!['node_modules','.git','.worktrees','lib'].includes(entry)) walk(`${path}/${entry}`);
+    } else if (/\.(tsx?|jsx?|mdx?)$/.test(path)) {
+      const input = readFileSync(path,'utf8'); const result = migrateFile(input,path,internal);
+      if (result.source !== input) { changed++; console.log(`${write ? 'update' : 'preview'} ${relative(process.cwd(),path)}`); if (write) writeFileSync(path,result.source); }
+      for (const warning of result.warnings) { pending++; console.error(`${relative(process.cwd(),path)}:${warning.line}: ${warning.reason}`); }
+    }
+  };
+  roots.forEach(walk);
+  console.log(`${write ? 'Updated' : 'Would update'} ${changed} files; ${pending} expressions need review.`);
+}

package/src/activity-feed/ActivityFeed.tsx

@@ -152,11 +152,11 @@ function ActivityFeedComponent({
               </Text>
               {long ? (
                 <Button
-                  variant="text"
+
                   size="xs"
                   onPress={() => toggle(entry.id)}
                   accessibilityLabel={`${open ? lessLabel : moreLabel}: ${entry.title}`}
-                  testID={eid('reveal')}
+                  testID={eid('reveal')} tone="accent" appearance="plain"
                 >
                   {open ? lessLabel : moreLabel}
                 </Button>

package/src/agent-progress/AgentProgress.tsx

@@ -1,7 +1,7 @@
 import { SurfacePaint } from '../surface/SurfacePaint';
 import { useSurfaceLayer } from '../surface/use-surface-layer';
-import { resolveSurfaceFill } from '../surface/shared';
-import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
+import { resolveSurfaceMaterial } from '../surface/resolve-surface-material';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 import { Platform, Pressable, StyleSheet, View, type ViewStyle } from 'react-native';
 import Animated, {
@@ -834,7 +834,8 @@ function AgentProgressComponent({
   const theme = useTheme();
   const surfaceLayer = useSurfaceLayer();
   const customSurface = StyleSheet.flatten(style);
-  const surfaceFill = resolveSurfaceFill(String(customSurface?.backgroundColor ?? surfaceLayer.fill), false, surfaceLayer.parentFill);
+  const material = resolveSurfaceMaterial({ fill: String(customSurface?.backgroundColor ?? surfaceLayer.fill), parentFill: surfaceLayer.parentFill, parentLevel: surfaceLayer.parentLevel });
+  const { paintFill: paintFill, publishedFill: surfaceFill } = material;
   const palette = resolvePalette(theme);
   const reducedMotion = useReducedMotion();
 
@@ -1002,10 +1003,10 @@ function AgentProgressComponent({
     <Animated.View
       aria-live="polite"
       testID={testID}
-      style={[styles.card, cardStatic, style, cardStyle, { backgroundColor: 'transparent', ...surfaceFillVars(surfaceFill) }]}
+      style={[styles.card, cardStatic, style, cardStyle, { backgroundColor: 'transparent', ...material.vars }]}
     >
-      <SurfacePaint fill={surfaceFill} radius={customSurface?.borderRadius ?? CARD_RADIUS} />
-      <SurfaceLevelProvider level={surfaceLayer.level} fill={surfaceFill}>
+      <SurfacePaint fill={paintFill} radius={customSurface?.borderRadius ?? CARD_RADIUS} />
+      <SurfaceLevelProvider level={material.level} fill={surfaceFill}>
       <Presence
         show={minimized}
         initial={false}

package/src/app-shell/AppShellMenuButton.tsx

@@ -25,15 +25,15 @@ const AppShellMenuButtonComponent: React.FC<AppShellMenuButtonProps> = ({
   if (!shell.drawerAvailable) return null;
   return (
     <Button
-      variant="secondary"
-      size="medium"
+
+      size="md"
       iconOnly
       leadingIcon={shell.drawerOpen ? RiCloseLine : RiMenuLine}
       accessibilityLabel={accessibilityLabel}
       aria-expanded={shell.drawerOpen}
       onPress={shell.toggleDrawer}
       style={style}
-      testID={testID}
+      testID={testID} tone="neutral" appearance="outline"
     />
   );
 };

package/src/app-shell/ProOfferCard.tsx

@@ -1,7 +1,7 @@
 import { SurfacePaint } from '../surface/SurfacePaint';
 import { useSurfaceLayer } from '../surface/use-surface-layer';
-import { resolveSurfaceFill } from '../surface/shared';
-import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
+import { resolveSurfaceMaterial } from '../surface/resolve-surface-material';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import React, { memo, useEffect, useMemo, useState } from 'react';
 import { Platform, StyleSheet, View, useWindowDimensions, type LayoutChangeEvent, type ViewStyle } from 'react-native';
 import Animated, {
@@ -164,7 +164,8 @@ const ProOfferCardComponent: React.FC<ProOfferCardProps> = ({
 
   const surfaceLayer = useSurfaceLayer();
   const customSurface = StyleSheet.flatten(style);
-  const surfaceFill = resolveSurfaceFill(String(customSurface?.backgroundColor ?? surfaceLayer.fill), false, surfaceLayer.parentFill);
+  const material = resolveSurfaceMaterial({ fill: String(customSurface?.backgroundColor ?? surfaceLayer.fill), parentFill: surfaceLayer.parentFill, parentLevel: surfaceLayer.parentLevel });
+  const { paintFill: paintFill, publishedFill: surfaceFill } = material;
   const enter = useSharedValue(reducedMotion ? 1 : 0);
   useEffect(() => {
     enter.value = reducedMotion ? 1 : withDelay(enterDelay, withTiming(1, { duration: 300, easing: EASE_OUT }));
@@ -221,11 +222,11 @@ const ProOfferCardComponent: React.FC<ProOfferCardProps> = ({
         },
         enterStyle,
         style,
-        { backgroundColor: 'transparent', ...surfaceFillVars(surfaceFill) },
+        { backgroundColor: 'transparent', ...material.vars },
       ]}
     >
-      <SurfacePaint fill={surfaceFill} radius={customSurface?.borderRadius ?? 16} />
-      <SurfaceLevelProvider level={surfaceLayer.level} fill={surfaceFill}>
+      <SurfacePaint fill={paintFill} radius={customSurface?.borderRadius ?? 16} />
+      <SurfaceLevelProvider level={material.level} fill={surfaceFill}>
       <View aria-hidden pointerEvents="none" style={backdropStyle}>
         {backdrop ?? <DefaultBackdrop from={palette.from} via={palette.via} />}
       </View>

package/src/booking/BookingCard.tsx

@@ -188,14 +188,14 @@ function BookingCardComponent({
       </View>
 
       <Button
-        variant="primary"
-        size="large"
+
+        size="lg"
         fullWidth
         onPress={onReserve}
         disabled={reserveDisabled}
         loading={loading}
         style={{ marginTop: 16, alignSelf: 'stretch' }}
-        testID={id('reserve')}
+        testID={id('reserve')} tone="accent" appearance="solid"
       >
         {buttonLabel}
       </Button>

package/src/booking/BookingLink.tsx

@@ -1,14 +1,14 @@
 import React from 'react';
 import type { GestureResponderEvent, StyleProp, TextStyle, ViewStyle } from 'react-native';
 
-import { Button } from '../button';
+import { LinkButton } from '../button';
 import type { TypeScaleVariant } from '../typography/scale';
 
 /**
  * INTERNAL — the family's underlined text button: a price row's label, the
  * guests panel's "Close", the bar's dates.
  *
- * It is `Button variant="link"` with the READING tone and the underline at rest
+ * It composes `LinkButton` with the READING tone and the underline at rest
  * (`linkTone="text"`, `underline="rest"`), which is exactly what it hand-rolled
  * before those two props existed: text-primary and underlined at rest,
  * text-secondary under a pointer or a press (colour only, no scale), a focus
@@ -48,12 +48,12 @@ export function BookingLink({
   ...handle
 }: BookingLinkProps) {
   return (
-    <Button
+    <LinkButton
       {...handle}
-      variant="link"
+
       linkTone="text"
       underline="rest"
-      size="small"
+      size="sm"
       textVariant={variant}
       onPress={onPress}
       disabled={disabled}
@@ -64,6 +64,6 @@ export function BookingLink({
       testID={testID}
     >
       {children}
-    </Button>
+    </LinkButton>
   );
 }

package/src/bottom-bar/BottomBar.tsx

@@ -1,10 +1,10 @@
 import { createTabBar, createTabBarButton } from '../tab-bar/TabBarBase';
-import { TranslucentTabBarSurface } from '../tab-bar/surface-translucent';
+import { SharedTabBarSurface } from '../tab-bar/surface-paint';
 import { ProgressiveBlur } from '../progressive-blur';
 import { BottomBarGlyph } from './glyph';
 import { BottomBarBase } from './BottomBarBase';
 import type { BottomBarProps } from './types';
-const Navigation = createTabBar(TranslucentTabBarSurface, ProgressiveBlur);
+const Navigation = createTabBar(SharedTabBarSurface, ProgressiveBlur);
 const Item = createTabBarButton(BottomBarGlyph);
 export function BottomBar(props: BottomBarProps) {
   return <BottomBarBase {...props} Navigation={Navigation} Item={Item} Blur={ProgressiveBlur} />;

package/src/bottom-bar/BottomBar.web.tsx

@@ -1,10 +1,10 @@
 import { createTabBar, createTabBarButton } from '../tab-bar/TabBarBase';
-import { TranslucentTabBarSurface } from '../tab-bar/surface-translucent';
+import { SharedTabBarSurface } from '../tab-bar/surface-paint';
 import { ProgressiveBlur } from '../progressive-blur/index.web';
 import { BottomBarGlyph } from './glyph';
 import { BottomBarBase } from './BottomBarBase';
 import type { BottomBarProps } from './types';
-const Navigation = createTabBar(TranslucentTabBarSurface, ProgressiveBlur);
+const Navigation = createTabBar(SharedTabBarSurface, ProgressiveBlur);
 const Item = createTabBarButton(BottomBarGlyph);
 export function BottomBar(props: BottomBarProps) {
   return <BottomBarBase {...props} Navigation={Navigation} Item={Item} Blur={ProgressiveBlur} />;

package/src/bottom-bar/BottomBarBase.tsx

@@ -80,7 +80,7 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
   return <View {...dirProps} testID={testID} pointerEvents="box-none" style={[{ height: bottom + footprint, justifyContent: 'flex-end' }, style]}>
     {blur && <Blur direction="bottom" style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: bottom + footprint + BLUR_BLEED }} />}
     <Animated.View testID={testID ? `${testID}-row` : undefined} onLayout={event => setRowWidth(event.nativeEvent.layout.width)} pointerEvents="box-none" style={[{ justifyContent: items.length ? 'center' : 'flex-end', alignSelf: 'center', width: '100%', maxWidth, paddingLeft: 12, paddingRight: 12, marginBottom: bottom, flexDirection: 'row', alignItems: 'center' }, rowStyle]}>
-      {items.length > 0 && <View testID={testID ? `${testID}-navigation` : undefined} style={{ width: navigationWidth, minWidth: 0 }}><ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={{ minWidth: '100%' }}><View style={{ width: Math.max(navigationWidth, items.length * 44 + 8) }}><Navigation scrollable={navigationWidth > 0 && navigationWidth < items.length * 44 + 8} embedded blur={false} material="translucent" minimizeProgress={progress}
+      {items.length > 0 && <View testID={testID ? `${testID}-navigation` : undefined} style={{ width: navigationWidth, minWidth: 0 }}><ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={{ minWidth: '100%' }}><View style={{ width: Math.max(navigationWidth, items.length * 44 + 8) }}><Navigation scrollable={navigationWidth > 0 && navigationWidth < items.length * 44 + 8} embedded blur={false} minimizeProgress={progress}
         activeProgress={activeProgress} onIndexLongPress={onValueLongPress ? index => { if (items[index]) onValueLongPress(items[index].name); } : undefined}
         activeIndex={items.findIndex(item => item.name === value)} onIndexChange={index => { if (items[index]) onValueChange(items[index].name); }}>
         {items.map((item, index) => <Item key={item.name} item={item} index={index} />)}

package/src/bottom-sheet/BottomSheetBase.tsx

@@ -1,45 +1,25 @@
+import { MOTION_RECIPES } from '../motion/recipes';
 import { surfaceStyle } from '../shapes/surface-style';
 import { SURFACE_SHAPES } from '../design-tokens/shapes';
 import type React from 'react';
 import { forwardRef, useImperativeHandle, useRef, useEffect, useState, useCallback, useMemo } from 'react';
-import {
-    View,
-    StyleSheet,
-    Pressable,
-    Dimensions,
-    Platform,
-    type LayoutChangeEvent,
-    type ViewStyle,
-    type StyleProp,
-} from 'react-native';
+import { View, StyleSheet, Dimensions, Platform, type ViewStyle, type StyleProp } from 'react-native';
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler';
 import { adoptStyleSheet, dropStyleSheet } from '../styles/adopt-style-sheet';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { SurfacePaint } from '../surface/SurfacePaint';
-import { resolveSurfaceFill } from '../surface/shared';
+import { resolveSurfaceMaterial } from '../surface/resolve-surface-material';
 import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
 import { ScreenScope } from '../layout';
 import { Z_INDEX } from '../styles/z-index';
-import Animated, {
-    type AnimatedStyle,
-    interpolate,
-    runOnJS,
-    type SharedValue,
-    useAnimatedScrollHandler,
-    useAnimatedReaction,
-    useAnimatedStyle,
-    useDerivedValue,
-    useSharedValue,
-    withSpring,
-    withTiming,
-} from 'react-native-reanimated';
+import Animated, { interpolate, runOnJS, useAnimatedScrollHandler, useAnimatedReaction, useAnimatedStyle, useDerivedValue, useSharedValue, withSpring, withTiming } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { EDGE_GAP, windowEdgeGap } from '../layout/edge';
 import { Backdrop, BACKDROP_DIM_OPACITY } from '../overlay';
 import { ModalKeyboard } from '../overlay/ModalKeyboard';
 import { useTheme } from '../theme/use-theme';
 import { SheetKeyboardProvider } from './context';
-import type { BottomSheetRef, BottomSheetProps, BottomSheetShellProps, BottomSheetBaseProps } from './types';
+import type { BottomSheetRef, BottomSheetBaseProps } from './types';
 
 /** Hook that returns current screen dimensions and updates on rotation/resize. */
 function useScreenDimensions() {
@@ -56,6 +36,7 @@ function useScreenDimensions() {
 }
 
 const SPRING_CONFIG = {
+    reduceMotion: MOTION_RECIPES.expand.reduceMotion,
     damping: 25,
     stiffness: 300,
     mass: 0.8,
@@ -210,14 +191,14 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
             // it eventually fires, because its captured generation is stale.
             closeGenerationRef.current += 1;
             closeGeneration.value = closeGenerationRef.current;
-            opacity.value = withTiming(1, { duration: 250 });
+            opacity.value = withTiming(1, { ...MOTION_RECIPES.present, duration: 250 });
             translateY.value = withSpring(0, SPRING_CONFIG);
         } else if (rendered) {
             // Capture the generation for THIS close cycle so the animation
             // callback (running on the UI thread, scheduled back to JS) and
             // the fallback timer agree on which cycle they belong to.
             const generation = closeGenerationRef.current;
-            opacity.value = withTiming(0, { duration: 250 }, (finished) => {
+            opacity.value = withTiming(0, { ...MOTION_RECIPES.dismiss, duration: 250 }, (finished) => {
                 if (finished) {
                     runOnJS(finishClose)(generation);
                 }
@@ -361,7 +342,7 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
                         // bumped the generation in between.
                         const generation = closeGeneration.value;
                         translateY.value = withSpring(screenHeightSV.value, { ...SPRING_CONFIG, velocity });
-                        opacity.value = withTiming(0, { duration: 250 }, (finished) => {
+                        opacity.value = withTiming(0, { ...MOTION_RECIPES.dismiss, duration: 250 }, (finished) => {
                             if (finished) runOnJS(finishClose)(generation);
                         });
                     } else {
@@ -420,7 +401,7 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
                         ...SPRING_CONFIG,
                         velocity: velocity,
                     });
-                    opacity.value = withTiming(0, { duration: 250 }, (finished) => {
+                    opacity.value = withTiming(0, { ...MOTION_RECIPES.dismiss, duration: 250 }, (finished) => {
                         if (finished) {
                             runOnJS(finishClose)(generation);
                         }
@@ -477,7 +458,7 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
                 if (shouldClose) {
                     const generation = closeGeneration.value;
                     translateY.value = withSpring(screenHeightSV.value, { ...SPRING_CONFIG, velocity });
-                    opacity.value = withTiming(0, { duration: 250 }, (finished) => {
+                    opacity.value = withTiming(0, { ...MOTION_RECIPES.dismiss, duration: 250 }, (finished) => {
                         if (finished) runOnJS(finishClose)(generation);
                     });
                 } else {
@@ -615,7 +596,9 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
 
     // The paint is absolute: gestures, measurements and layout stay on the existing sheet.
     const flatSurfaceStyle = StyleSheet.flatten(style as StyleProp<ViewStyle>);
-    const surfaceFill = resolveSurfaceFill(String(backgroundFill ?? flatSurfaceStyle?.backgroundColor ?? colors.background), false, colors.background);
+    const backingFill = String(backgroundFill ?? flatSurfaceStyle?.backgroundColor ?? colors.background);
+    const material = resolveSurfaceMaterial({ fill: backingFill, parentFill: colors.background, paint: !backgroundComponent, level: 0 });
+    const { paintFill, publishedFill: surfaceFill } = material;
     const surfaceRadius = flatSurfaceStyle?.borderRadius ?? flatSurfaceStyle?.borderTopLeftRadius ?? 24;
     const surfaceCorners: ViewStyle = {
         ...surfaceStyle({ curve: SURFACE_SHAPES.panel.curve }),
@@ -766,12 +749,12 @@ export const BottomSheetBase = forwardRef((props: BottomSheetBaseProps, ref: Rea
                         {backgroundComponent ? backgroundComponent({ style: styles.background }) : (
                             <View pointerEvents="none" style={[StyleSheet.absoluteFill, surfaceCorners, { overflow: 'hidden' }]}>
                                 <View pointerEvents="none" style={[StyleSheet.absoluteFill, { bottom: detached ? 0 : -(typeof surfaceRadius === 'number' ? surfaceRadius : 24) }]}>
-                                    <SurfacePaint fill={surfaceFill} shape={{ curve: SURFACE_SHAPES.panel.curve }} radius={surfaceRadius} />
+                                    <SurfacePaint fill={paintFill} shape={{ curve: SURFACE_SHAPES.panel.curve }} radius={surfaceRadius} />
                                 </View>
                             </View>
                         )}
 
-                        <SurfaceLevelProvider level={0} fill={surfaceFill}>
+                        <SurfaceLevelProvider level={material.level} fill={surfaceFill}>
                         {handleSlot}
 
                         {bodyContent}