Communitygithub.com

aktiva-labs/Claude-Skill-Compendium

Cria animações em React Native e Expo, tomando as decisões na ordem que determina se elas parecem certas — deve animar, em qual thread executa, quais propriedades, spring ou timing, como o gesto faz a transição, como degrada. Escreve a implementação com Reanimated, Gesture Handler, Expo Router e expo-haptics. Use ao animar qualquer coisa em um app Expo, adicionar gestos, sheets, transições de tela, feedback de toque ou haptics, ou corrigir movimento que trava no dispositivo. Para animação web use `animate`.

O que é Claude-Skill-Compendium?

Esta skill é um guia completo para construir animações em React Native e Expo que pareçam naturais e responsivas em dispositivos reais, baseado na filosofia de animação de Emil Kowalski. Ela prioriza a execução no thread da IU (UI runtime) usando Reanimated 4 e Gesture Handler para evitar travamentos, e estabelece uma sequência de decisões rigorosa: primeiro determinar se a animação é necessária, depois escolher a ferramenta mais simples (como transições CSS do Reanimated para mudanças simples, ou `useSharedValue` para gestos), selecionar propriedades eficientes (priorizando `transform` e `opacity`), configurar timing ou spring com parâmetros precisos, e garantir que o movimento nunca bloqueie o thread JavaScript. A skill também cobre feedback tátil com `expo-haptics`, suporte a `ReduceMotion` para acessibilidade, e configurações como `presentation: 'formSheet'` para sheets nativas ou `NativeTabs` para abas. Ela funciona em qualquer projeto Expo com React Native, mas é especificamente otimizada para Expo Router e requer a instalação correta dos pacotes via `npx expo install`.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/aktiva-labs/Claude-Skill-Compendium/tree/HEAD/emilkowalski-skills/skills/animate-expo

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construindo Animações no Expo

Resposta Inicial

Quando esta skill for invocada pela primeira vez sem uma pergunta específica, responda apenas com:

Estou pronto para construir animações no Expo e React Native que pareçam certas em um dispositivo real, meu conhecimento vem da filosofia de animação de Emil Kowalski.

Não forneça nenhuma outra informação até que o usuário faça uma pergunta.

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 telefone topo de linha em modo de desenvolvimento.

O mobile muda três coisas sobre animação, e tudo nesta skill decorre delas:

  1. Não existe hover. Cada affordance que a web coloca no hover tem que viver no toque, na posição ou em nada.
  2. Existem dois runtimes. Worklets (Reanimated 4) torna isso explícito: o runtime do React Native, onde o React renderiza e sua lógica de aplicativo é executada, e o runtime da IU, onde os worklets são executados a cada frame (mais runtimes de worker opcionais para trabalho em segundo plano). Uma animação que toca o runtime do React Native trava no momento em que o aplicativo faz qualquer outra coisa. Toda a arte é manter o movimento no runtime da IU.
  3. O dedo do usuário está no elemento. Gestos são a entrada primária, então a capacidade de interrupção e a transferência de velocidade não são um polimento — são a linha de base.

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:

  1. Animar algo que não deveria animar. A comporta abaixo existe para produzir zero linhas de código às vezes.
  2. Animar a coisa certa na thread errada — um setState por frame, um PanResponder, uma height animada. Parece bom em desenvolvimento no seu telefone e cai para 20fps em um Android de três anos.

Regras Rígidas

  1. Execute a sequência em ordem. As etapas 1 e 2 controlam tudo.
  2. Reanimated, não o Animated principal. O Animated principal não pode ser direcionado por um gesto sem cruzar a ponte, e useNativeDriver se recusa a qualquer coisa que não seja transform e opacidade. Os worklets do Reanimated são executados no thread da IU e continuam em execução enquanto o JS está ocupado.
  3. Sem valores aproximados. Curvas e configurações de spring vêm das tabelas abaixo.
  4. Movimento reduzido acompanha a animação, não como um complemento.
  5. 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ênciaDecisão
100+ vezes/dia — troca de abas, abrir/fechar teclado, rolagem, alternâncias em configuraçõesSem animação. Padrão da plataforma ou nada. Pare por aqui.
Dezenas de vezes/dia — feedback de toque, navegação em lista, seleção de linhaApenas quase imperceptível: abaixo de 150ms, ou nada
Ocasional — sheets, modais, toasts, etapas de integraçãoAnimação padrão
Raro / primeira vez — estados de sucesso, ilustrações de estado vazio, celebraçãoO orçamento de encantamento 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 nesta comporta, diga isso e não a escreva.

2. Qual é o propósito?

Nomeie-o em uma palavra antes de continuar: feedback, consistência espacial, indicação de estado, prevenir uma mudança brusca, explicação ou encantamento (apenas camada rara).

Não consegue nomear? Não construa.

3. Escolha a ferramenta — a mais barata que funciona

Caminhe para baixo; pare na primeira que se encaixar.

NecessidadeFerramenta
Uma mudança orientada por estado sem gesto — toque, alternância, cor, um valor mudandoTransição CSS do Reanimated (transitionProperty no estilo)
Loop, vários estágios, ou é reproduzido na montagem sem mudança de estadoAnimação CSS do Reanimated (animationName keyframes)
Um elemento montando ou desmontando, ou uma lista refluindoAnimações de layout (entering / exiting / itemLayoutAnimation)
Qualquer coisa que um dedo toque, ou qualquer coisa derivada de rolagemuseSharedValue + Gesture + useAnimatedStyle
Tela para telaOpções de stack nativas no Expo Router. Nunca faça isso manualmente
Uma bottom sheet que é sua própria telapresentation: 'formSheet' — é um UISheetPresentationController real, gratuito e correto
Barra de abasNativeTabs (de expo-router/unstable-native-tabs) — a barra de abas real da plataforma, seus comportamentos e transições incluídos
Menu de contexto, visualização pressionando e segurandoLink.Menu / Link.Preview (Expo Router, apenas iOS) — menus e visualizações nativos, nunca reconstruídos em JS
Cabeçalho que recolhe em um título grandeheaderLargeTitleEnabled na stack nativa (apenas iOS; headerLargeTitle está obsoleto) — não um worklet de rolagem
Puxar para atualizarRefreshControl — faça manualmente apenas quando for uma interação característica (veja a receita de limite)
IU que acompanha o tecladoreact-native-keyboard-controller — a posição real do teclado, quadro a quadro, no thread da IU
Ilustração vetorial, celebração, estado vazioLottie — apenas para ilustração, nunca para estado de IU
Uma cena animada enorme, desenho livre@shopify/react-native-skia — uma tela, para quando a própria hierarquia de visualização é o gargalo

Recorra a um valor compartilhado apenas quando o valor for contínuo ou interrompível. Uma escala de toque é uma transição CSS; um arrasto é um valor compartilhado. Usar um worklet para uma alternância de dois estados é o equivalente mobile de instalar uma biblioteca de movimento para um fade.

Dependências. Instale com npx expo install <pacote> — ele resolve a versão que corresponde ao SDK do projeto, o que npm install simples não fará:

NecessidadePacote
Animaçãoreact-native-reanimated + react-native-worklets
Gestosreact-native-gesture-handler
Navegação, sheets, abas nativas, menusexpo-router
Hapticsexpo-haptics
IU que segue o tecladoreact-native-keyboard-controller (precisa de KeyboardProvider na raiz — veja a receita de teclado)
Ilustração, celebraçãolottie-react-native
Cenas animadas muito grandes, desenho personalizado@shopify/react-native-skia

4. Escolha as propriedades

  • transform e opacity são gratuitos. Todo o resto é uma passagem de layout. width, height, margin, padding, flex, top, left, gap executam Yoga novamente a 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. Está fora do fluxo, então nada mais re-layout, e animar width mantém o raio de canto que scaleX borraria.
  • Nunca scale(0). Comece de scale(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, a translate também é escalada. 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 pré-sombreada.
  • Nunca anime BlurView intensity. No Android, re-renderiza o desfoque a cada frame. Faça crossfade da opacidade de um BlurView estático.
  • Porcentagens funcionam em translate e são relativas ao tamanho do próprio elemento — translateY('100%') move uma sheet pela sua própria altura, qualquer que seja seu conteúdo.

5. Timing ou spring

Se um dedo esteve envolvido, use spring. Springs carregam a velocidade através de uma interrupção; curvas de timing reiniciam. Todo o resto usa timing.

O spring do Reanimated recebe os dois parâmetros de designer da Apple diretamente — use esta forma, não massa/rigidez/amortecimento:

InteraçãoConfig
Estabilização padrão, sem overshoot{ duration: 400, dampingRatio: 1 }
Reposicionar / voltar após um arrasto{ duration: 400, dampingRatio: 0.8, velocity }
Sheet, gaveta{ duration: 300, dampingRatio: 0.8, velocity }
Não deve ultrapassar uma borda rígidaadd overshootClamping: true

Bounce apenas quando o gesto carregou momentum. Overshoot em um menu que apareceu parece errado; overshoot em um cartão que você lançou parece certo.

Easing, para tudo sem um dedo:

SituaçãoEasing
Entrando ou saindoease-out
Movendo / transformando na telaease-in-out
Movimento constante (progresso, marquee)linear
Padrãoease-out

Nunca ease-in na IU. Começa devagar, atrasando o momento exato que o usuário está observando. Os embutidos 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);      // strong ease-out para IU
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:

ElementoDuração
Feedback de toque100–150ms
Alternância, chip, pequena mudança de estado150–200ms
Sheet, modal, gavetaspring, ~300ms percebidos
Transição de telao padrão da plataforma — não substitua

Animações de IU mobile ficam abaixo de 300ms, assim como na web. As próprias transições da plataforma são mais longas (push do iOS é 350ms); corresponda à plataforma para navegação, supere em todos os outros lugares.

6. Mantenha fora do thread JS

Este é o ofício específico do mobile, e é onde a maior parte do movimento do React Native morre.

  • Nunca setState de um manipulador de gesto ou rolagem. Uma renderização do React por frame é a maior causa de travamentos em apps RN. Valor compartilhado → useAnimatedStyle, e React nunca re-renderiza.
  • Nunca agende de volta para o runtime RN dentro de onUpdate ou um manipulador de rolagem. scheduleOnRN(fn, ...args) de react-native-worklets — a substituição do Reanimated 4 para o obsoleto runOnJS(fn)(...args) — enfileira uma chamada do runtime RN, e em onUpdate isso é 60–120× por segundo. Pertence a onEnd, ou em um useAnimatedReaction que dispara quando um valor cruza um limite.
  • Nunca leia um valor compartilhado durante a renderização (translateY.get() no JSX). É um instantâneo que nunca atualiza e silenciosamente dessincroniza. Nunca escreva um durante a renderização também — dispara no meio da reconciliação, e uma re-renderização que você não causou repete a escrita. Toque valores compartilhados apenas em worklets, handlers e effects.
  • Use .get() / .set(), não .value. Mesma API, mas o acesso direto a .value é a forma que o React Compiler não consegue ver através — a documentação do Reanimated chama get/set de maneira segura para o compilador. set também aceita uma atualização funcional: sv.set((v) => v + 1).
  • Funções chamadas de um worklet precisam de 'worklet' como sua primeira linha, ou lançam erro em tempo de execução no dispositivo enquanto funcionam bem no depurador.

7. Toque, não hover

Toda affordance de hover da web precisa ser redesenhada, não portada.

  • Feedback ao pressionar, compromisso ao soltar. Esperar o toque ser concluído antes de mostrar qualquer coisa parece morto — esta é a latência que o usuário realmente percebe.
  • scale: 0.97 em 100–150ms em qualquer elemento pressionável, Pressable + uma transição CSS. scale leva o rótulo e os ícones junto, que é o que o faz ser lido como físico.
  • Alvo de toque mínimo de 44×44pt (48dp Android). Se o visual for menor, adicione hitSlop — não aumente o visual.
  • pressRetentionOffset para que um dedo deslizando alguns pixels não cancele um toque que o usuário pretendia.
  • Ripple do Android apenas em um app estilizado com Material. Em um app com design personalizado, a mesma escala em ambas as plataformas é mais coerente do que um ripple em uma.

8. Haptics

O mobile tem um sentido que a web não tem. Use com moderação e se torna a coisa que faz o app parecer caro; use em todos os lugares e os usuários desligam.

MomentoChamada
Um valor passa por um passo — seletor, detente de slider, controle segmentadoHaptics.selectionAsync()
Algo encaixa no lugar, um detente de sheet pega, um arrasto confirmaHaptics.impactAsync(ImpactFeedbackStyle.Light)
Um objeto pesado aterrissa, uma ação destrutiva disparaHaptics.impactAsync(ImpactFeedbackStyle.Medium)
Operação bem-sucedida ou falhouHaptics.notificationAsync(NotificationFeedbackType.Success / Error)

Três regras, e são absolutas:

  • Mesmo frame que o visual. Um háptico que atrasa sua animação parece um glitch, não um feedback. Dispare no momento causal — o detente pegando — não quando a animação termina.
  • Um por ação do usuário. Nunca na rolagem, nunca por frame, nunca em uma animação de entrada que o usuário não causou.
  • Nunca o único feedback. Haptics estão desligados em todo o sistema para muitos usuários e silenciosos na maioria do hardware Android. O visual tem que se sustentar sozinho.

De um worklet, hápticos devem ser agendados de volta para o runtime RN: scheduleOnRN(Haptics.selectionAsync).

9. Movimento reduzido e acessibilidade

import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';

const reduced = useReducedMotion();
const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);

// ou deixe cada animação decidir
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });

Movimento reduzido significa menos e mais suave, não zero: mantenha mudanças de opacidade e cor que explicam uma mudança de estado, remova translação, escala, parallax e overshoot. Transições de tela tornam-se animation: 'fade'.

Escalas de texto. allowFontScaling está ligado por padrão, então qualquer altura que você mediu no tamanho de tipo padrão está errada em 200%. Nunca anime para uma altura codificada — meça com onLayout, ou anime uma transformação.

Configuração que silenciosamente quebra o movimento

Verifique estas primeiro quando "a animação simplesmente não executa":

  • Instale através do Expo para que as versões correspondam ao SDK: npx expo install react-native-reanimated react-native-worklets. Em um projeto Expo, babel-preset-expo configura o plugin Babel de worklets automaticamente — sem etapa babel.config.js. Apenas um projeto RN puro sem esse preset adiciona o plugin manualmente, e mesmo assim você deveria preferir o Expo para novos projetos.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

aktiva-labs/Claude-Skill-Compendium

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

aktiva-labs/Claude-Skill-Compendium

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

aktiva-labs/Claude-Skill-Compendium

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

aktiva-labs/Claude-Skill-Compendium

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

aktiva-labs/Claude-Skill-Compendium

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

Habilidades Relacionadas