Diretrizes de UI do Expo

Quando Usar

Use esta habilidade quando precisar de um guia completo para criar aplicativos bonitos com o Expo Router. Abrange fundamentos, estilização, componentes, navegação, animações, padrões e abas nativas.

Referências

Consulte estes recursos conforme necessário:

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+)

Executando o Aplicativo

CRÍTICO: Sempre tente o Expo Go primeiro antes de criar builds personalizados.

A maioria dos aplicativos Expo funciona no Expo Go sem nenhum código nativo personalizado. Antes de executar npx expo run:ios ou npx expo run:android:

1. Comece com o Expo Go: Execute npx expo start e escaneie o código QR com o Expo Go
2. Verifique se os recursos funcionam: Teste seu aplicativo completamente no Expo Go
3. Crie builds personalizados apenas quando necessário - veja abaixo

Quando Builds Personalizados São Necessários

Você precisa de npx expo run:ios/android ou eas build APENAS ao usar:

• Módulos Expo locais (código nativo personalizado em modules/)
• Alvos da Apple (widgets, app clips, extensões via @bacons/apple-targets)
• Módulos nativos de terceiros não incluídos no Expo Go
• Configuração nativa personalizada que não pode ser expressa em app.json

Quando o Expo Go Funciona

O Expo Go suporta uma vasta gama de recursos prontos para uso:

• Todos os pacotes expo-* (câmera, localização, notificações, etc.)
• Navegação do Expo Router
• A maioria das bibliotecas de UI (reanimated, gesture handler, etc.)
• Notificações push, links profundos e mais

Se tiver dúvidas, tente o Expo Go primeiro. Criar builds personalizados adiciona complexidade, lentidão na iteração e requer configuração do Xcode/Android Studio.

Estilo de Código

• Tenha cuidado com strings não terminadas. Certifique-se de que as crases aninhadas sejam escapadas; nunca se esqueça de escapar as aspas corretamente.
• Sempre use declarações import no topo do arquivo.
• Sempre use kebab-case para nomes de arquivos, por exemplo, comment-card.tsx
• Sempre remova arquivos de rota antigos ao mover ou reestruturar a navegação
• Nunca use caracteres especiais em nomes de arquivos
• Configure tsconfig.json com aliases de caminho e prefira aliases em vez de importações relativas para refatorações.

Rotas

Veja ./references/route-structure.md para convenções de rota detalhadas.

• As rotas pertencem ao diretório app.
• Nunca co-aloque componentes, tipos ou utilitários no diretório app. Isso é um anti-padrão.
• Certifique-se de que o aplicativo sempre tenha uma rota que corresponda a "/", ela pode estar dentro de uma rota de grupo.

Preferências de Biblioteca

• Nunca use módulos removidos do React Native, como Picker, WebView, SafeAreaView ou AsyncStorage
• Nunca use expo-permissions legado
• expo-audio em vez de expo-av
• expo-video em vez de expo-av
• expo-image com source="sf:name" para SF Symbols, não expo-symbols ou @expo/vector-icons
• react-native-safe-area-context em vez de react-native SafeAreaView
• process.env.EXPO_OS em vez de Platform.OS
• React.use em vez de React.useContext
• O componente de Imagem expo-image em vez do elemento intrínseco img
• expo-glass-effect para backdrops de vidro líquido
• Color de expo-router para cores semânticas nativas, em vez de PlatformColor bruto (type-safe, adapta-se automaticamente a claro/escuro)
• No SDK 56+, nunca importe diretamente de @react-navigation/* — use expo-router/react-navigation em vez disso (cobre @react-navigation/native, /core, /elements, /routers)

Responsividade

• Sempre envolva o componente raiz em uma ScrollView para responsividade

…