Construyendo Animaciones en Expo
Este repositorio (Asymmetric-al/core)
Este skill es solo para movimiento en React Native / Expo. Las apps Next.js de Core deben usar animate, emil-design-engineering y anim. Revisa esta superposición después de refrescar las upstream antes de ejecutar bun run skills:sync.
Disparadores
- Trabajo explícito de animación, gestos, hojas o hápticos en Expo o React Native.
- No lo cargues para apps web de Core (
apps/admin,apps/donor,apps/missionary) o para paquetes compartidospackages/uide movimiento web.
Flujo de Trabajo
- Confirma que la solicitud sea nativa/Expo antes de aplicar recetas de Reanimated.
- Para superficies Core Next.js, detente y carga
animatemásanim.
Lista de Verificación
- El entorno de ejecución objetivo es Expo/React Native, no las apps Core con App Router.
- El movimiento web sigue usando tokens Core y Base UI.
Un skill de construcción para React Native. Convierte una solicitud de movimiento en una implementación que sobrevive una revisión estricta en un dispositivo real, no en el simulador ni en un teléfono insignia en modo desarrollo.
El móvil cambia tres cosas sobre la animación, y todo en este skill se deriva de ellas:
- No hay hover. Cada funcionalidad que el web pone en el hover tiene que vivir en la presión, la posición o en ninguna parte.
- Hay dos tiempos de ejecución. Los Worklets (Reanimated 4) lo hacen explícito: el tiempo de ejecución de React Native, donde React renderiza y tu lógica de la app se ejecuta, y el tiempo de ejecución de UI, donde los worklets se ejecutan cada frame (además de tiempos de ejecución worker opcionales para trabajo en segundo plano). Una animación que toca el tiempo de ejecución de RN se traba en el momento en que la app hace cualquier otra cosa. Todo el arte consiste en mantener el movimiento en el tiempo de ejecución de UI.
- El dedo del usuario está sobre el elemento. Los gestos son la entrada principal, por lo que la interrumpibilidad y la transferencia de velocidad no son un lujo, son la base.
Postura Operativa
Eres un ingeniero senior de móvil que construye la animación tú mismo. Toma la decisión, expresa el razonamiento en una línea, escribe el código. Nunca presentes opciones de movimiento como un menú.
Dos modos de fallo, y el primero es peor:
- Animar algo que no debería animarse. La compuerta de abajo existe para producir cero líneas de código a veces.
- Animar lo correcto en el hilo equivocado — un
setStatepor frame, unPanResponder, unheightanimado. Se ve bien en desarrollo en tu teléfono y baja a 20fps en un Android de tres años.
Reglas Estrictas
- Ejecuta la secuencia en orden. Los pasos 1 y 2 lo controlan todo.
- Reanimated, no
Animatedcore. ElAnimatedcore no puede ser impulsado por un gesto sin cruzar el puente, yuseNativeDriverrechaza cualquier cosa que no sea transform y opacity de todas formas. Los worklets de Reanimated se ejecutan en el hilo de UI y siguen ejecutándose mientras JS está ocupado. - Sin valores aproximados. Las curvas y configuraciones de spring provienen de las tablas de abajo.
- El movimiento reducido se entrega con la animación, no como un seguimiento.
- La sensación se juzga en una compilación de lanzamiento en el dispositivo más lento que soportes. Nada más cuenta como verificado.
La Secuencia de Construcción
1. ¿Debería esto animarse?
| Frecuencia | Decisión |
|---|---|
| 100+ veces/día — cambios de pestaña, apertura/cierre de teclado, desplazamiento, alternar en ajustes | Sin animación. Valor por defecto de la plataforma o nada. Detente aquí. |
| Decenas de veces/día — retroalimentación de presión, navegación por lista, selección de fila | Casi imperceptible solo: menos de 150ms, o nada |
| Ocasional — hojas, modales, toasts, pasos de onboarding | Animación estándar |
| Rara / primera vez — estados de éxito, ilustraciones de estado vacío, celebración | El presupuesto de deleite vive aquí |
Los cambios de pestaña nunca se deslizan. Las pestañas son pares, no una jerarquía — deslizar implica una profundidad que no existe, y el usuario lo paga docenas de veces por sesión. animation: 'none'.
Si la solicitud falla esta compuerta, dilo y no la escribas.
2. ¿Cuál es el propósito?
Nómbralo en una palabra antes de continuar: retroalimentación, consistencia espacial, indicación de estado, prevenir un cambio brusco, explicación o deleite (solo nivel raro).
¿No puedes nombrarlo? No lo construyas.
3. Elige la herramienta — la más barata que funcione
Camina hacia abajo; detente en la primera que encaje.
| Necesidad | Herramienta |
|---|---|
| Un cambio impulsado por estado sin gesto — presión, alternar, color, un valor que cambia | Transición CSS de Reanimated (transitionProperty en el estilo) |
| Bucle, multi-etapa, o se ejecuta al montar sin cambio de estado | Animación CSS de Reanimated (animationName keyframes) |
| Un elemento montándose o desmontándose, o una lista refluyendo | Animaciones de layout (entering / exiting / itemLayoutAnimation) |
| Cualquier cosa que el dedo toque, o cualquier cosa derivada del desplazamiento | useSharedValue + Gesture + useAnimatedStyle |
| Pantalla a pantalla | Opciones de pila nativa en Expo Router. Nunca lo hagas manualmente |
| Una hoja inferior que es su propia pantalla | presentation: 'formSheet' — es un UISheetPresentationController real, gratuito y correcto |
| Barra de pestañas | NativeTabs (de expo-router/unstable-native-tabs) — la barra de pestañas real de la plataforma, con sus comportamientos y transiciones incluidos |
| Menú contextual, vista previa de mantener presionado | Link.Menu / Link.Preview (Expo Router, solo iOS) — menús nativos y peek, nunca reconstruidos en JS |
| Encabezado que colapsa en un título grande | headerLargeTitleEnabled en la pila nativa (solo iOS; headerLargeTitle está obsoleto) — no un scroll worklet |
| Desplazar para actualizar | RefreshControl — hazlo manualmente solo cuando sea una interacción característica (ver la receta de umbral) |
| UI que sigue al teclado | react-native-keyboard-controller — la posición real del teclado, frame por frame, en el hilo de UI |
| Ilustración vectorial, celebración, estado vacío | Lottie — solo para ilustración, nunca para estado de UI |
| Una escena animada enorme, dibujo libre | @shopify/react-native-skia — un canvas, para cuando la jerarquía de vistas es el cuello de botella |
Alcanza un valor compartido solo cuando el valor es continuo o interrumpible. Una escala de presión es una transición CSS; un arrastre es un valor compartido. Usar un worklet para un alternar de dos estados es el equivalente móvil de instalar una biblioteca de movimiento para un fundido.
Dependencias. Instala con npx expo install <package> — resuelve la versión que coincide con el SDK del proyecto, que npm install simple no hará:
| Necesidad | Paquete |
|---|---|
| Animación | react-native-reanimated + react-native-worklets |
| Gestos | react-native-gesture-handler |
| Navegación, hojas, pestañas nativas, menús | expo-router |
| Hápticos | expo-haptics |
| UI que sigue al teclado | react-native-keyboard-controller (necesita KeyboardProvider en la raíz — ver la receta del teclado) |
| Ilustración, celebración | lottie-react-native |
| Escenas animadas muy grandes, dibujo personalizado | @shopify/react-native-skia |
4. Elige las propiedades
transformyopacityson gratuitos. Todo lo demás es un pase de layout.width,height,margin,padding,flex,top,left,gapre-ejecutan Yoga en cada frame para ese nodo y sus hermanos.- La única excepción: un elemento posicionado absolutamente sin hijos — una pastilla de pestaña, un relleno de barra de progreso. Está fuera del flujo, así que nada más se reorden, y animar
widthmantiene el radio de esquina quescaleXmancharía. - Nunca
scale(0). Comienza desdescale(0.9–0.97)+opacity: 0. Nada en el mundo real aparece de la nada. transformes un array y el orden importa —[{ translateY }, { scale }]escala después de mover; invertido, el translate también se escala. Mantén translate primero a menos que quieras la multiplicación.- Las sombras en Android son
elevation, y animar elevation re-renderiza la sombra cada frame. Anima la opacidad de una capa con sombra predefinida en su lugar. - Nunca animes la intensidad de
BlurView. En Android re-renderiza el desenfoque cada frame. Haz un fundido cruzado de la opacidad de unBlurViewestático en su lugar. - Los porcentajes funcionan en
translatey son relativos al tamaño propio del elemento —translateY('100%')mueve una hoja por su propia altura sin importar su contenido.
5. Timing o spring
Si un dedo estuvo involucrado, usa un spring. Los springs llevan la velocidad a través de una interrupción; las curvas de timing reinician. Todo lo demás usa timing.
El spring de Reanimated toma los dos parámetros de diseño de Apple directamente — usa esta forma, no masa/rigidez/amortiguación:
| Interacción | Config |
|---|---|
| Ajuste predeterminado, sin sobreimpulso | { duration: 400, dampingRatio: 1 } |
| Reposición / snap back después de un arrastre | { duration: 400, dampingRatio: 0.8, velocity } |
| Hoja, cajón | { duration: 300, dampingRatio: 0.8, velocity } |
| No debe pasar un borde duro | añade overshootClamping: true |
Rebote solo cuando el gesto llevó impulso. Un sobreimpulso en un menú que apareció suave se siente mal; un sobreimpulso en una tarjeta que lanzaste se siente bien.
Easing, para todo sin un dedo encima:
| Situación | Easing |
|---|---|
| Entrando o saliendo | ease-out |
| Moviéndose / cambiando en pantalla | ease-in-out |
| Movimiento constante (progreso, marquesina) | linear |
| Predeterminado | ease-out |
Nunca ease-in en UI. Comienza lento, retrasando el momento exacto que el usuario está mirando. Los built-in de Reanimated son tan débiles como los de CSS — usa estos:
import { Easing } from "react-native-reanimated";
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out para UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // movimiento en pantalla
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // curva de hoja iOS
Duración:
| Elemento | Duración |
|---|---|
| Retroalimentación de presión | 100–150ms |
| Alternar, chip, pequeño cambio de estado | 150–200ms |
| Hoja, modal, cajón | spring, ~300ms percibido |
| Transición de pantalla | el valor por defecto de la plataforma — no lo sobrescribas |
Las animaciones de UI en móvil se mantienen por debajo de los 300ms, igual que en web. Las transiciones propias de la plataforma son más largas (el push de iOS es 350ms); iguala la plataforma para navegación, supérala en todo lo demás.
6. Mantenlo fuera del hilo de JS
Este es el arte específico del móvil, y es donde la mayoría del movimiento en React Native muere.
- Nunca
setStatedesde un manejador de gestos o desplazamiento. Un render de React por frame es la mayor causa única de tirones en apps RN. Valor compartido →useAnimatedStyle, y React nunca re-renderiza en absoluto. - Nunca programes de vuelta al tiempo de ejecución de RN dentro de
onUpdateo un manejador de desplazamiento.scheduleOnRN(fn, ...args)dereact-native-worklets— el reemplazo de Reanimated 4 para el obsoletorunOnJS(fn)(...args)— pone en cola una llamada al tiempo de ejecución de RN, y enonUpdateeso es 60–120 veces por segundo. Pertenece aonEnd, o a unuseAnimatedReactionque se dispara cuando un valor cruza un umbral. - Nunca leas un valor compartido durante el render (
translateY.get()en JSX). Es una instantánea que nunca se actualiza y silenciosamente rompe la reactividad. useAnimatedPropspara propiedades nativas. Si tienes que pasar un valor animado a un componente nativo que no acepta un estilo animado (comoMapView), usauseAnimatedProps— no envuelvas un valor compartido a través de un puente tú mismo.withSpringywithTimingen worklets, no en JS. Estas funciones de animación deben ejecutarse dentro de un worklet (en el hilo de UI) para iniciar la animación desde allí. Llamarlas desde JS las inicia en el hilo de UI de todas formas, pero la recomendación es mantenerlas en worklets.- Verifica los hilos en
react-native-reanimateddevtools. El inspector de animaciones muestra qué valores se ejecutan en el hilo de UI y cuáles cruzan el puente.
7. Movimiento reducido
import { useReducedMotion } from "react-native-reanimated";
const reducedMotion = useReducedMotion();
// luego: `reducedMotion ? <sin animación> : <animación>`
No alternes nada. Solo reduce: duración a 0, escala de 1, opacidad de 1. El usuario ha dicho que prefiere menos movimiento, no movimiento diferente.
Para entrada/salida: entering={FadeIn.duration(reducedMotion ? 0 : 200)}.
Para animaciones continuas: Lottie tiene su propio reduceMotion: true.
En layouts nativos (pestañas, hojas, stacks nativos), el sistema maneja el movimiento reducido. No toques UISheetPresentationController ni UITabBar.
Contraejemplos que este skill previene
| Bajo el capó | Por qué está mal |
|---|---|
Animated.Value / Animated.timing | Escrito para el Animated core. Reescrito con Reanimated useSharedValue + withTiming. |
PanResponder | Escrito con el sistema de gestos heredado. Reescrito con react-native-gesture-handler. |
style={{ width: animatedWidth }} | Animar a través de layout. Cambiado a transform: [{ scaleX }] o a un elemento posicionado absolutamente. |
onUpdate={(value) => setState({ value })} | El render empuja la animación de vuelta al hilo de JS cada frame. Reescrito con useAnimatedStyle. |
useAnimatedStyle con funciones que no son worklets | La función pasa valores por referencia que son del hilo de JS. Reescrito con solo valores compartidos y worklets. |
Sin verificación de useReducedMotion | Saltada. Añadida en la definición de animación. |
Animated.spring con masa/rigidez/amortiguación | No coinciden con los parámetros de diseño de Apple. Reescrito con duración/relación de amortiguación. |
Recetas
Escala de presión de botón
// Paso 3: transición CSS de Reanimated — ningún gesto involucrado
// Paso 5: ease-out, 120ms
// Paso 7: useReducedMotion
const scaleStyle = useAnimatedStyle(() => ({
transform: [{ scale: pressed.value ? 0.96 : 1 }],
}), [pressed]);
// Como transición CSS:
<Animated.View style={[style, { transitionProperty: 'transform', transitionDuration: 120, transitionEasing: EASE_OUT }, scaleStyle]}>
{children}
</Animated.View>
Hoja con arrastre
const translateY = useSharedValue(0);
const gesture = Gesture.Pan()
.onUpdate((e) => {
translateY.value = Math.max(0, e.translationY);
})
.onEnd((e) => {
if (translateY.value > SHEET_THRESHOLD) {
// cerrar
} else {
translateY.value = withSpring(0, { duration: 300, dampingRatio: 0.8, velocity: e.velocityY });
}
});
const animatedStyle = useAnimatedStyle(() => ({
transform: [{ translateY: translateY.value }],
}));
Animación de entrada para un toast
<Animated.View entering={FadeInDown.duration(200).easing(EASE_OUT)}>
<Toast />
</Animated.View>
Notas Específicas de la Plataforma
iOS
UISheetPresentationControllerse maneja conpresentation: 'formSheet'en Expo Router. No personalices su animación — es correcta.UITabBarconNativeTabs. El sistema maneja las transiciones.UINavigationControllerpara stacks nativos.headerLargeTitleEnabledpara títulos grandes — no un scroll worklet.- Las vistas previas de menú y peek de enlaces usan
Link.Menu/Link.Preview. - El deslizamiento para retroceder es gratuito con el stack nativo.
Android
- Las sombras (
elevation) se renderizan en la CPU y son caras de animar. Anima la opacidad de una capa pre-sombreada. BlurViewre-renderiza el desenfoque cada frame — cruza la opacidad de un estático.- No hay hoja nativa en Android; usa
react-native-reanimated+Gesturepara hojas. - Los gestos de Android son más sensibles por defecto;
react-native-gesture-handlermaneja esto.
Web (exclusión)
Este skill es solo para móvil. Si este proyecto se despliega en web, el equipo web debe usar sus propios skills (animate, emil-design-engineering, anim). Las animaciones web deben seguir tokens Core y Base UI. No portes recetas móviles a web.
Resumen Rápido
- ¿Debería? — Sí, solo si la frecuencia lo justifica.
- ¿Propósito? — Nómbralo en una palabra.
- ¿Herramienta? — La más barata que funcione (desde transición CSS hasta Skia).
- ¿Propiedades? — transform y opacity son gratuitos.
- ¿Spring o timing? — Dedo = spring; sin dedo = timing.
- ¿Hilo de JS? — Nunca; usa valores compartidos y worklets.
- ¿Movimiento reducido? — Siempre.
No hay paso 8. Escribe el código.