Construindo Animações no Expo
Este repositório (Asymmetric-al/core)
Esta skill é exclusiva para motion em React Native / Expo. Os apps Next.js do Core devem
usar animate, emil-design-engineering e anim. Reconcilie este
overlay após atualizações upstream antes de executar bun run skills:sync.
Gatilhos
- Trabalho explícito com animação, gestos, sheets ou haptics no Expo ou React Native.
- Não carregue para apps web do Core (
apps/admin,apps/donor,apps/missionary) ou para motion web do pacote compartilhadopackages/ui.
Fluxo de Trabalho
- Confirme que a solicitação é nativa/Expo antes de aplicar receitas do Reanimated.
- Para superfícies Core Next.js, pare e carregue
animateeanim.
Checklist
- O alvo é Expo/React Native, não apps do App Router do Core.
- Motion web ainda segue os tokens do Core e a Base UI.
Uma skill de construção para React Native. Ela transforma uma solicitação de movimento em uma implementação que sobrevive a uma revisão rigorosa em um dispositivo real — não no simulador, não em um smartphone topo de linha em modo de desenvolvimento.
O mobile muda três coisas sobre animação, e tudo nesta skill segue delas:
- Não existe hover. Cada affordance que a web coloca no hover precisa viver no pressionar, na posição ou no nada.
- Existem dois runtimes. Worklets (Reanimated 4) tornam isso explícito: o runtime do React Native, onde o React renderiza e sua lógica de app executa, e o runtime da UI, onde os worklets executam a cada frame (mais runtimes de worker opcionais para trabalho em segundo plano). Uma animação que toca o runtime do RN trava no momento em que o app faz qualquer outra coisa. Toda a arte é manter o motion no runtime da UI.
- O dedo do usuário está sobre o elemento. Gestos são a entrada primária, portanto interrompibilidade e passagem de velocidade não são polish — são o padrão.
Postura Operacional
Você é um engenheiro mobile sênior construindo a animação você mesmo. Tome a decisão, declare o raciocínio em uma linha, escreva o código. Nunca apresente opções de movimento como um menu.
Dois modos de falha, e o primeiro é pior:
- Animar algo que não deveria ser animado. O portão abaixo existe para produzir zero linhas de código às vezes.
- Animar a coisa certa na thread errada — um
setStatepor frame, umPanResponder, umaheightanimada. Parece bom no desenvolvimento no seu telefone e cai para 20fps em um Android de três anos.
Regras Rígidas
- Execute a sequência em ordem. As etapas 1 e 2 controlam tudo.
- Reanimated, não o
Animatednativo. OAnimatednativo não pode ser impulsionado por um gesto sem cruzar a ponte, euseNativeDriverrecusa tudo exceto transform e opacity. Worklets do Reanimated executam na thread da UI e continuam executando enquanto o JS está ocupado. - Sem valores aproximados. Curvas e configurações de spring vêm das tabelas abaixo.
- Reduced motion é enviado junto com a animação, não como um follow-up.
- A sensação é julgada em uma build de release no dispositivo mais lento que você suporta. Nada mais conta como verificado.
A Sequência de Construção
1. Isso deve animar?
| Frequência | Decisão |
|---|---|
| 100+ vezes/dia — troca de abas, abrir/fechar teclado, rolagem, toggles em configurações | Sem animação. Padrão da plataforma ou nada. Pare aqui. |
| Dezenas de vezes/dia — feedback de press, navegação em listas, seleção de linhas | Quase imperceptível apenas: abaixo de 150ms, ou nada |
| Ocasional — sheets, modais, toasts, etapas de onboarding | Animação padrão |
| Raro / primeira vez — estados de sucesso, ilustrações de estado vazio, celebração | O orçamento de delight vive aqui |
Trocas de aba nunca deslizam. Abas são pares, não uma hierarquia — deslizar implica profundidade que não existe, e o usuário paga por isso dezenas de vezes por sessão. animation: 'none'.
Se a solicitação falhar neste portão, diga isso e não escreva.
2. Qual é o propósito?
Nomeie em uma palavra antes de continuar: feedback, consistência espacial, indicação de estado, prevenir uma mudança brusca, explicação ou delight (apenas camada rara).
Não consegue nomear? Não construa.
3. Escolha a ferramenta — a mais barata que funciona
Desça; pare na primeira que se encaixar.
| Necessidade | Ferramenta |
|---|---|
| Uma mudança controlada por estado sem gesto — press, toggle, cor, valor alternando | Transição CSS do Reanimated (transitionProperty no estilo) |
| Loop, multi-estágio, ou executa na montagem sem mudança de estado | Animação CSS do Reanimated (animationName keyframes) |
| Um elemento montando ou desmontando, ou uma lista reorganizando | Animações de layout (entering / exiting / itemLayoutAnimation) |
| Qualquer coisa que um dedo toque, ou qualquer coisa derivada de rolagem | useSharedValue + Gesture + useAnimatedStyle |
| Tela para tela | Opções nativas de stack no Expo Router. Nunca faça manualmente |
| Uma bottom sheet que é sua própria tela | presentation: 'formSheet' — é um UISheetPresentationController real, gratuito e correto |
| Barra de abas | NativeTabs (de expo-router/unstable-native-tabs) — a barra de abas real da plataforma, seus comportamentos e transições inclusos |
| Menu de contexto, preview pressionar e segurar | Link.Menu / Link.Preview (Expo Router, apenas iOS) — menus e peek nativos, nunca reconstruídos em JS |
| Cabeçalho que recolhe em um título grande | headerLargeTitleEnabled no stack nativo (apenas iOS; headerLargeTitle está obsoleto) — não um scroll worklet |
| Puxar para atualizar | RefreshControl — faça manualmente apenas quando for uma interação característica (veja a receita de limite) |
| UI que acompanha o teclado | react-native-keyboard-controller — a posição real do teclado, frame a frame, na thread da UI |
| Ilustração vetorial, celebração, estado vazio | Lottie — apenas para ilustração, nunca para estado de UI |
| Uma cena animada enorme, desenho livre | @shopify/react-native-skia — um canvas, para quando a hierarquia de views em si é o gargalo |
Recorra a um shared value apenas quando o valor for contínuo ou interrompível. Uma escala de press é uma transição CSS; um arrasto é um shared value. Usar um worklet para um toggle de dois estados é o equivalente mobile de instalar uma biblioteca de motion para um fade.
Dependências. Instale com npx expo install <package> — ele resolve a versão que corresponde ao SDK do projeto, que npm install simples não resolve:
| Necessidade | Pacote |
|---|---|
| Animação | react-native-reanimated + react-native-worklets |
| Gestos | react-native-gesture-handler |
| Navegação, sheets, abas nativas, menus | expo-router |
| Haptics | expo-haptics |
| UI que acompanha o teclado | react-native-keyboard-controller (precisa de KeyboardProvider na raiz — veja a receita de teclado) |
| Ilustração, celebração | lottie-react-native |
| Cenas animadas muito grandes, desenho personalizado | @shopify/react-native-skia |
4. Escolha as propriedades
transformeopacitysão gratuitos. Todo o resto é uma passagem de layout.width,height,margin,padding,flex,top,left,gapreexecutam Yoga em cada frame para aquele nó e seus irmãos.- A única exceção: um elemento posicionado absolutamente sem filhos — uma pílula de aba, um preenchimento de barra de progresso. Ele está fora do fluxo, então nada mais se reorganiza, e animar
widthmantém o raio de borda quescaleXdistorceria. - Nunca
scale(0). Comece descale(0.9–0.97)+opacity: 0. Nada no mundo real aparece do nada. transformé um array e a ordem importa —[{ translateY }, { scale }]escala após mover; invertido, o translate também é escalado. Mantenha translate primeiro, a menos que queira a multiplicação.- Sombras no Android são
elevation, e animar elevation re-renderiza a sombra a cada frame. Anime a opacidade de uma camada previamente sombreada. - Nunca anime a intensidade do
BlurView. No Android ele re-renderiza o desfoque a cada frame. Faça crossfade da opacidade de umBlurViewestático. - Porcentagens funcionam em
translatee são relativas ao tamanho do próprio elemento —translateY('100%')move uma sheet pela sua própria altura independentemente do conteúdo.
5. Timing ou spring
Se um dedo esteve envolvido, use spring. Springs carregam velocidade através de uma interrupção; curvas de timing reiniciam. Todo o resto usa timing.
O spring do Reanimated aceita os dois parâmetros de design da Apple diretamente — use esta forma, não massa/rigidez/amortecimento:
| Interação | Config |
|---|---|
| Ajuste padrão, sem overshoot | { duration: 400, dampingRatio: 1 } |
| Reposicionar / snap back após um arrasto | { duration: 400, dampingRatio: 0.8, velocity } |
| Sheet, drawer | { duration: 300, dampingRatio: 0.8, velocity } |
| Não deve ultrapassar uma borda rígida | adicione overshootClamping: true |
Bounce apenas quando o gesto carregou momentum. Overshoot em um menu que apareceu gradualmente parece errado; overshoot em um cartão que você lançou parece certo.
Easing, para tudo sem um dedo:
| Situação | Easing |
|---|---|
| Entrando ou saindo | ease-out |
| Movendo / morfando na tela | ease-in-out |
| Movimento constante (progresso, marquee) | linear |
| Padrão | ease-out |
Nunca ease-in na UI. Ele começa devagar, atrasando o exato momento que o usuário está observando. Os built-ins do Reanimated são tão fracos quanto os do CSS — use estes:
import { Easing } from "react-native-reanimated";
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // ease-out forte para UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // movimento na tela
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // curva de sheet do iOS
Duração:
| Elemento | Duração |
|---|---|
| Feedback de press | 100–150ms |
| Toggle, chip, pequena mudança de estado | 150–200ms |
| Sheet, modal, drawer | spring, ~300ms percebido |
| Transição de tela | o padrão da plataforma — não sobrescreva |
Animações de UI mobile ficam abaixo de 300ms, assim como na web. As transições da própria plataforma são mais longas (push do iOS é 350ms); corresponda à plataforma para navegação, supere em todo o resto.
6. Mantenha fora da thread JS
Esta é a arte específica do mobile, e é onde a maioria dos movimentos em React Native morre.
- Nunca
setStatea partir de um manipulador de gesto ou rolagem. Uma renderização React por frame é a maior causa de jank em apps RN. Shared value →useAnimatedStyle, e React nunca re-renderiza. - Nunca agende de volta para o runtime do RN dentro de
onUpdateou de um manipulador de rolagem.scheduleOnRN(fn, ...args)dereact-native-worklets— o substituto para o obsoletorunOnJS(fn)(...args)no Reanimated 4 — enfileira uma chamada no runtime do RN, e emonUpdateisso é 60–120× por segundo. Pertence aonEnd, ou a umuseAnimatedReactionque dispara quando um valor cruza um limiar. - Nunca leia um shared value durante a renderização (
translateY.get()em JSX). É um snapshot que nunca atualiza e silenciosamente quebra toda a animação. Acesse shared values dentro de worklets ouuseAnimatedStyle.