ranbot-ai/building-native-ui

Expo UI Guidelines

When to Use

• You are building a native-feeling Expo Router application and need guidance on navigation, controls, effects, or platform-specific UI.
• You need to decide whether Expo Go is sufficient or a custom native build is actually required.
• The task involves modern Expo UI patterns across animations, tabs, headers, storage, media, or visual effects.

References

Consult these resources as needed:

references/
  animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures
  controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
  form-sheet.md          Form sheets in expo-router: configuration, footers and background interaction. 
  gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
  icons.md               SF Symbols via expo-image (sf: source), names, animations, weights
  media.md               Camera, audio, video, and file saving
  route-structure.md     Route conventions, dynamic routes, groups, folder organization
  search.md              Search bar with headers, useSearch hook, filtering patterns
  storage.md             SQLite, AsyncStorage, SecureStore
  tabs.md                NativeTabs, migration from JS tabs, iOS 26 features
  toolbar-and-headers.md Stack headers and toolbar buttons, menus, search (iOS only)
  visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)
  webgpu-three.md        3D graphics, games, GPU visualizations with WebGPU and Three.js
  zoom-transitions.md    Apple Zoom: fluid zoom transitions with Link.AppleZoom (iOS 18+)

Running the App

CRITICAL: Always try Expo Go first before creating custom builds.

Most Expo apps work in Expo Go without any custom native code. Before running npx expo run:ios or npx expo run:android:

1. Start with Expo Go: Run npx expo start and scan the QR code with Expo Go
2. Check if features work: Test your app thoroughly in Expo Go
3. Only create custom builds when required - see below

When Custom Builds Are Required

You need npx expo run:ios/android or eas build ONLY when using:

• Local Expo modules (custom native code in modules/)
• Apple targets (widgets, app clips, extensions via @bacons/apple-targets)
• Third-party native modules not included in Expo Go
• Custom native configuration that can't be expressed in app.json

When Expo Go Works

Expo Go supports a huge range of features out of the box:

• All expo-* packages (camera, location, notifications, etc.)
• Expo Router navigation
• Most UI libraries (reanimated, gesture handler, etc.)
• Push notifications, deep links, and more

If you're unsure, try Expo Go first. Creating custom builds adds complexity, slower iteration, and requires Xcode/Android Studio setup.

Code Style

• Be cautious of unterminated strings. Ensure nested backticks are escaped; never forget to escape quotes correctly.
• Always use import statements at the top of the file.
• Always use kebab-case for file names, e.g. comment-card.tsx
• Always remove old route files when moving or restructuring navigation
• Never use special characters in file names
• Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.

Routes

See ./references/route-structure.md for detailed route conventions.

• Routes belong in the app directory.
• Never co-locate components, types, or utilities in the app directory. This is an anti-pattern.
• Ensure the app always has a route that matches "/", it may be inside a group route.

Library Preferences

• Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage
• Never use legacy expo-permissions
• expo-audio not expo-av
• expo-video not expo-av
• expo-image with source="sf:name" for SF Symbols, not expo-symbols or @expo/vector-icons
• react-native-safe-area-context not react-native SafeAreaView
• process.env.EXPO_OS not Platform.OS
• React.use not React.useContext
• expo-image Image component instead of intrinsic element img
• expo-glass-effect for liquid glass backdrops

Responsiveness

• Always wrap root component in a scroll view for responsiveness
• Use <ScrollView contentInsetAdjustmentBehavior="automatic" /> instead of <SafeAreaView> for smarter safe area insets
• contentInsetAdjustmentBehavior="automatic" should be applied to FlatList and SectionList as well
• Use flexbox instead of Dimensions API
• ALWAYS prefer useWindowDimensions over Dimensions.get() to measure screen size

Behavior

• Use expo-haptics conditionally on iOS to make more delightful experiences
• Use views with built-in haptics like <Switch /> from React Native and @react-native-community/datetimepicker
• When a route belongs to a Stack, its first child should almost always be a ScrollView with contentInsetAdjustmentBehavior="automatic" set
• When addi