Communitygithub.com

therts649-ai/Claude-Skills

Cria animações em React Native e Expo, tomando 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 algo em um app Expo, adicionar gestos, sheets, transições de tela, feedback de pressionamento ou hápticos, ou ao corrigir movimentos que travam no dispositivo. Para animação web, use `animate`.

O que é Claude-Skills?

Esta habilidade é um guia especializado para construir animações de alta qualidade em React Native e Expo, seguindo uma filosofia focada em desempenho real em dispositivos móveis. Ela estabelece um processo de tomada de decisão em etapas, começando pela pergunta fundamental 'isso deve animar?' e nomeando o propósito da animação antes de qualquer implementação. O objetivo principal é manter a animação na thread da IU (UI thread), evitando travamentos causados por chamadas ao runtime do React Native durante quadros críticos. A habilidade abrange uma ampla gama de cenários, desde feedback de pressionamento e transições de tela até gestos complexos e folhas modais (sheets), priorizando o uso de bibliotecas modernas como `react-native-reanimated` e `react-native-gesture-handler`. Além disso, inclui regras sobre hápticos, acessibilidade com movimento reduzido e um guia de configuração para evitar problemas comuns que silenciosamente quebram animações.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/therts649-ai/Claude-Skills/tree/HEAD/plugins/emil-design/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 em Expo

Resposta Inicial

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

Estou pronto para construir animações em Expo e React Native que parecem 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 habilidade 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 celular principal em modo de desenvolvimento.

Dispositivos móveis mudam três coisas sobre animação, e tudo nesta habilidade segue a partir delas:

  1. Não há hover. Toda conveniência que a web coloca no hover tem que viver em pressionamento, posição ou 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 app executa, e o runtime da IU, onde os worklets executam a cada frame (mais runtimes de worker opcionais para trabalho em segundo plano). Uma animação que toca no runtime do RN trava no momento em que o app 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 interrompibilidade e transferência de velocidade não são 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 barreira 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 modo de 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. Os Passos 1 e 2 barram tudo.
  2. Reanimated, não o Animated principal. O Animated principal não pode ser conduzido por um gesto sem cruzar a ponte, e useNativeDriver recusa qualquer coisa além de transform e opacity de qualquer maneira. Worklets do Reanimated executam na thread da IU e continuam executando enquanto o JS está ocupado.
  3. Sem valores aproximados. Curvas e configurações de spring vêm das tabelas abaixo.
  4. Movimento reduzido vem com a animação, não como um acompanhamento.
  5. A sensação é julgada em uma versão de lançamento 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 — trocas de aba, abrir/fechar teclado, rolagem, alternâncias em configuraçõesSem animação. Padrão da plataforma ou nada. Pare aqui.
Dezenas de vezes/dia — feedback de pressionamento, 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 barreira, 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 nível raro).

Não consegue nomear? Não construa.

3. Escolha a ferramenta — a mais barata que funciona

Desça; pare na primeira que se encaixa.

NecessidadeFerramenta
Uma mudança orientada por estado sem gesto — press, toggle, cor, um valor alternandoTransição CSS do Reanimated (transitionProperty no estilo)
Loop, multiestágio, ou executa na montagem sem mudança de estadoAnimação CSS do Reanimated (animationName keyframes)
Um elemento montando ou desmontando, ou uma lista reorganizandoAnimações de layout (entering / exiting / itemLayoutAnimation)
Qualquer coisa que um dedo toca, ou qualquer coisa derivada de rolagemuseSharedValue + Gesture + useAnimatedStyle
Tela para telaOpções de pilha nativa no Expo Router. Nunca faça 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, pré-visualização de pressionar e segurarLink.Menu / Link.Preview (Expo Router, somente iOS) — menus nativos e visualização, nunca reconstruídos em JS
Cabeçalho que colapsa em um título grandeheaderLargeTitleEnabled na pilha nativa (somente 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 segue o tecladoreact-native-keyboard-controller — a posição real do teclado, frame a frame, na thread da IU
Ilustração vetorial, celebração, estado vazioLottie — apenas para ilustração, nunca para estado da IU
Uma cena animada enorme, desenho livre@shopify/react-native-skia — um canvas, para quando a hierarquia de visualização em si é o gargalo

Recorra a um shared value apenas quando o valor for contínuo ou interrompível. Um escala de pressão é uma transição CSS; um arrasto é um shared value. 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 puro não fará:

NecessidadePacote
Animaçãoreact-native-reanimated + react-native-worklets
Gestosreact-native-gesture-handler
Navegação, sheets, abas nativas, menusexpo-router
Hápticosexpo-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 passada de layout. width, height, margin, padding, flex, top, left, gap reexecutam Yoga 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 se reorganiza, e animar width mantém o raio do 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, 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 com sombra pré-renderizada.
  • Nunca anime a intensidade do BlurView. No Android, ele re-renderiza o desfoque a cada frame. Faça uma transição cruzada 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 por sua própria altura, independentemente de seu conteúdo.

5. Timing ou spring

Se um dedo esteve envolvido, use um spring. Springs carregam 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çãoConfiguração
Estabilização padrão, sem ultrapassagem{ duration: 400, dampingRatio: 1 }
Reposicionamento / retorno após um arrasto{ duration: 400, dampingRatio: 0.8, velocity }
Sheet, gaveta{ duration: 300, dampingRatio: 0.8, velocity }
Não deve ultrapassar um limite rígidoadicione overshootClamping: true

Ultrapassagem apenas quando o gesto carregou momentum. A ultrapassagem em um menu que surgiu com fade parece errada; a ultrapassagem em um cartão que você lançou parece certa.

Easing, para tudo sem um dedo sobre ele:

SituaçãoEasing
Entrando ou saindoease-out
Movendo / transformando na telaease-in-out
Movimento constante (progresso, letreiro)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 for UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1);  // on-screen movement
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1);    // iOS sheet curve

Duração:

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

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

6. Mantenha fora da thread JS

Este é o ofício específico do mobile, e é onde a maioria dos movimentos em React Native morre.

  • Nunca setState a partir de um manipulador de gesto ou rolagem. Uma renderização do React por frame é a maior causa de travamentos em apps RN. Shared value → useAnimatedStyle, e o React nunca re-renderiza.
  • Nunca agende de volta para o runtime do 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 a um useAnimatedReaction que dispara quando um valor cruza um limite.
  • Nunca leia um shared value durante a renderização (translateY.get() em JSX). É um instantâneo que nunca atualiza e dessincroniza silenciosamente. Nunca escreva um durante a renderização também — isso dispara no meio da reconciliação, e uma re-renderização que você não causou reproduz a escrita. Toque em shared values apenas em worklets, handlers e efeitos.
  • Use .get() / .set(), não .value. Mesma API, mas o acesso direto a .value é a forma que o React Compiler não consegue enxergar — a documentação do Reanimated chama get/set de forma 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 um erro em tempo de execução no dispositivo enquanto funcionam bem no depurador.

7. Pressionamento, não hover

Toda conveniência de hover da web tem que ser redesenhada, não portada.

  • Feedback ao pressionar, confirmar ao soltar. Esperar o toque terminar 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 pressionável, Pressable + uma transição CSS. scale leva o rótulo e os ícones junto, que é o que o faz parecer 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 desviando alguns pixels não cancele um pressionamento que o usuário pretendia.
  • Ripple no 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. Hápticos

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

MomentoChamada
Um valor passa por um passo — seletor, detent de slider, controle segmentadoHaptics.selectionAsync()
Algo encaixa no lugar, um detent de sheet pega, um arrasto é confirmadoHaptics.impactAsync(ImpactFeedbackStyle.Light)
Um objeto pesado pousa, uma ação destrutiva é acionadaHaptics.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 uma falha, não um feedback. Dispare-o no momento causal — o detent 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. Os hápticos estão desligados no sistema para muitos usuários, e são silenciosos na maioria dos hardwares Android. O visual tem que se sustentar sozinho.

A partir de um worklet, os hápticos devem ser agendados de volta para o runtime do 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 opacidade e mudanças de cor que explicam uma mudança de estado, remova translação, escala, paralaxe e ultrapassagem. As transições de tela se tornam animation: 'fade'.

Escalas de texto. allowFontScaling está ativado por padrão, então qualquer altura que você mediu no tamanho de fonte 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 do worklet automaticamente — sem etapa de babel.config.js. Apenas um projeto RN puro sem esse preset adiciona o plugin manualmente, e

…

[truncado para tradução]

Individual skills in this repo

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

Habilidades Relacionadas