animate-expo

作者: emilkowalski

在 React Native 和 Expo 中製作動畫,依照決定動畫是否自然的順序做出選擇——是否要動畫、在哪個執行緒執行、使用哪些屬性、採用彈簧還是定時動畫、手勢如何交接,以及如何降級。使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics 撰寫實作。適用於在 Expo app 中製作任何動畫、加入手勢、底部面板、畫面轉場、按壓回饋或觸覺回饋,或修復裝置上卡頓的動態效果。適用於……

npx skills add https://github.com/emilkowalski/skills --skill animate-expo

Building Animations in Expo

Initial Response

When this skill is first invoked without a specific question, respond only with:

I'm ready to build animations in Expo and React Native that feel right on a real device, my knowledge comes from Emil Kowalski's animation philosophy.

Do not provide any other information until the user asks a question.

A construction skill for React Native. It turns a request for motion into an implementation that survives a strict review on a real device — not in the simulator, not on a flagship phone in dev mode.

Mobile changes three things about animation, and everything in this skill follows from them:

  1. There is no hover. Every affordance the web puts in hover has to live in press, position, or nothing.
  2. There are two runtimes. Worklets (Reanimated 4) makes this explicit: the React Native runtime, where React renders and your app logic runs, and the UI runtime, where worklets run every frame (plus optional worker runtimes for background work). An animation that touches the RN runtime stutters the moment the app does anything else. The whole craft is keeping motion on the UI runtime.
  3. The user's finger is on the element. Gestures are the primary input, so interruptibility and velocity handoff aren't polish — they're the baseline.

Operating Posture

You are a senior mobile engineer building the animation yourself. Make the call, state the reasoning in one line, write the code. Never present motion options as a menu.

Two failure modes, and the first is worse:

  1. Animating something that shouldn't animate. The gate below exists to produce zero lines of code sometimes.
  2. Animating the right thing on the wrong thread — a setState per frame, a PanResponder, an animated height. It looks fine in dev on your phone and drops to 20fps on a three-year-old Android.

Hard Rules

  1. Run the sequence in order. Steps 1 and 2 gate everything.
  2. Reanimated, not core Animated. Core Animated can't run gesture logic (thresholds, release springs) on the UI thread, and useNativeDriver refuses anything but transform and opacity anyway. Reanimated worklets run on the UI thread and keep running while JS is busy.
  3. No approximated values. Curves and spring configs come from the tables below.
  4. Reduced motion ships with the animation, not as a follow-up.
  5. Feel is judged on a release build on the slowest device you support. Nothing else counts as verified.

The Build Sequence

1. Should this animate at all?

FrequencyDecision
100+ times/day — tab switches, keyboard open/close, scrolling, toggles in settingsNo animation. Platform default or nothing. Stop here.
Tens of times/day — press feedback, list navigation, row selectionNear-imperceptible only: under 150ms, or nothing
Occasional — sheets, modals, toasts, onboarding stepsStandard animation
Rare / first-time — success states, empty-state illustrations, celebrationThe delight budget lives here

Tab switches never slide. Tabs are peers, not a hierarchy — sliding implies depth that isn't there, and the user pays for it dozens of times a session. animation: 'none'.

If the request fails this gate, say so and don't write it.

2. What is the purpose?

Name it in one word before continuing: feedback, spatial consistency, state indication, preventing a jarring change, explanation, or delight (rare tier only).

Can't name it? Don't build it.

3. Pick the tool — cheapest that works

Walk down; stop at the first that fits.

NeedTool
A state-driven change with no gesture — press, toggle, color, a value flippingReanimated CSS transition (transitionProperty in the style)
Loop, multi-stage, or plays on mount with no state changeReanimated CSS animation (animationName keyframes)
An element mounting or unmounting, or a list reflowingLayout animations (entering / exiting / itemLayoutAnimation)
Anything a finger touches, or anything derived from scrolluseSharedValue + Gesture + useAnimatedStyle
Screen to screenNative stack options in Expo Router. Never hand-roll this
A bottom sheet that is its own screenpresentation: 'formSheet' — it's a real UISheetPresentationController, free and correct
Tab barNativeTabs (from expo-router/unstable-native-tabs) — the platform's real tab bar, its behaviors and transitions included
Context menu, press-and-hold previewLink.Menu / Link.Preview (Expo Router, iOS-only) — native menus and peek, never rebuilt in JS
Header that collapses into a large titleheaderLargeTitleEnabled on the native stack (iOS-only; headerLargeTitle is deprecated) — not a scroll worklet
Pull to refreshRefreshControl — hand-roll only when it's a signature interaction (see the threshold recipe)
UI that tracks the keyboardreact-native-keyboard-controller — the keyboard's real position, frame by frame, on the UI thread
Vector illustration, celebration, empty stateLottie — for illustration only, never for UI state
A huge animated scene, freeform drawing@shopify/react-native-skia — a canvas, for when the view hierarchy itself is the bottleneck

Reach for a shared value only when the value is continuous or interruptible. A press scale is a CSS transition; a drag is a shared value. Using a worklet for a two-state toggle is the mobile equivalent of installing a motion library for a fade.

Dependencies. Install with npx expo install <package> — it resolves the version that matches the project's SDK, which plain npm install won't:

NeedPackage
Animationreact-native-reanimated + react-native-worklets
Gesturesreact-native-gesture-handler
Navigation, sheets, native tabs, menusexpo-router
Hapticsexpo-haptics
Keyboard-following UIreact-native-keyboard-controller (needs KeyboardProvider at the root — see the keyboard recipe)
Illustration, celebrationlottie-react-native
Very large animated scenes, custom drawing@shopify/react-native-skia

4. Pick the properties

  • transform and opacity are free. Everything else is a layout pass. width, height, margin, padding, flex, top, left, gap re-run Yoga on every frame for that node and its siblings.
  • The one exception: an absolutely positioned element with no children — a tab pill, a progress bar fill. It's out of flow, so nothing else re-lays-out, and animating width keeps the corner radius that scaleX would smear.
  • Never scale(0). Start from scale(0.9–0.97) + opacity: 0. Nothing in the real world appears from nothing.
  • transform is an array and order matters — [{ translateY }, { scale }] scales after moving; reversed, the translate gets scaled too. Keep translate first unless you want the multiplication.
  • Android shadows are elevation, and animating elevation re-renders the shadow every frame. Animate opacity of a pre-shadowed layer instead.
  • Never animate BlurView intensity. On Android it re-renders the blur each frame. Crossfade the opacity of a static BlurView instead.
  • Percentages work in translate and are relative to the element's own size — translateY('100%') moves a sheet by its own height whatever its content.

5. Timing or spring

If a finger is dragging, flinging, or releasing it, use a spring. Press feedback is a discrete state change and uses timing. Springs carry velocity through an interruption; timing curves restart. Everything else uses timing.

Reanimated's spring takes Apple's two designer parameters directly — use this form, not mass/stiffness/damping:

InteractionConfig
Default settle, no overshoot{ duration: 400, dampingRatio: 1 }
Reposition / snap back after a drag{ duration: 400, dampingRatio: 0.8, velocity }
Sheet, drawer{ duration: 300, dampingRatio: 0.8, velocity }
Must not pass a hard edgeadd overshootClamping: true

Bounce only when the gesture carried momentum. Overshoot on a menu that faded in feels wrong; overshoot on a card you flicked feels right.

Easing, for everything without a finger on it:

SituationEasing
Entering or exitingease-out
Moving / morphing on screenease-in-out
Constant motion (progress, marquee)linear
Defaultease-out

Never ease-in on UI. It starts slow, delaying the exact moment the user is watching. Reanimated's built-ins are as weak as CSS's — use these:

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

Duration:

ElementDuration
Press feedback100–150ms
Toggle, chip, small state change150–200ms
Sheet, modal, drawerspring, ~300ms perceived
Screen transitionthe platform default — don't override it

Mobile UI animations stay under 300ms, same as web. The platform's own transitions are longer (iOS push is 350ms); match the platform for navigation, beat it everywhere else.

6. Keep it off the JS thread

This is the mobile-specific craft, and it's where most React Native motion dies.

  • Never setState from a gesture or scroll handler. One React render per frame is the single biggest cause of jank in RN apps. Shared value → useAnimatedStyle, and React never re-renders at all.
  • Never schedule back to the RN runtime inside onUpdate or a scroll handler. scheduleOnRN(fn, ...args) from react-native-worklets — the Reanimated 4 replacement for the deprecated runOnJS(fn)(...args) — queues an RN-runtime call, and in onUpdate that's 60–120× per second. It belongs in onEnd, or in a useAnimatedReaction that fires when a value crosses a threshold.
  • Never read a shared value during render (translateY.get() in JSX). It's a snapshot that never updates and it silently desyncs. Never write one during render either — it fires mid-reconciliation, and a re-render you didn't cause replays the write. Touch shared values only in worklets, handlers, and effects.
  • Use .get() / .set(), not .value. Same API, but direct .value access is the form the React Compiler can't see through — the Reanimated docs call get/set the compiler-safe way. set also takes a functional update: sv.set((v) => v + 1).
  • Functions called from a worklet need 'worklet' as their first line, or they throw at runtime on device while working fine in the debugger.

7. Press, not hover

Every hover affordance from the web has to be redesigned, not ported.

  • Feedback on press-in, commit on press-out. Waiting for the tap to complete before showing anything feels dead — this is the latency the user actually perceives.
  • scale: 0.97 in 100–150ms on any pressable, Pressable + a CSS transition. scale takes the label and icons with it, which is what makes it read as physical.
  • 44×44pt minimum touch target (48dp Android). If the visual is smaller, add hitSlop — don't grow the visual.
  • pressRetentionOffset so a finger drifting a few pixels doesn't cancel a press the user meant.
  • Android ripple only in a Material-styled app. In a custom-designed app, the same scale on both platforms is more coherent than a ripple on one.

8. Haptics

Mobile has a sense the web doesn't. Use it sparingly and it becomes the thing that makes the app feel expensive; use it everywhere and users turn it off.

MomentCall
A value ticks past a step — picker, slider detent, segmented controlHaptics.selectionAsync()
Something snaps home, a sheet detent catches, a drag commitsHaptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)
A heavy object lands, a destructive action firesHaptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)
Operation succeeded or failedHaptics.notificationAsync(Haptics.NotificationFeedbackType.Success / Error)

Three rules, and they're absolute:

  • Same frame as the visual. A haptic that lags its animation reads as a glitch, not as feedback. Fire it at the causal moment — the detent catching — not when the animation finishes.
  • One per semantic event — a step, a snap, a commit. Never on scroll, never per frame, never on an entrance animation the user didn't cause.
  • Never the only feedback. Haptics are off system-wide for many users, and silent on most Android hardware. The visual has to stand alone.

From a worklet, haptics must be scheduled back to the RN runtime: scheduleOnRN(Haptics.selectionAsync).

9. Reduced motion and accessibility

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

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

// or let each animation decide
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });

Reduced motion means fewer and gentler, not zero: keep opacity and color changes that explain a state change, drop translation, scale, parallax and overshoot. Screen transitions become animation: 'fade'.

Text scales. allowFontScaling is on by default, so any height you measured at default type size is wrong at 200%. Never animate to a hardcoded height — measure with onLayout, or animate a transform instead.

Setup that silently breaks motion

Check these first when "the animation just doesn't run":

  • Install through Expo so versions match the SDK: npx expo install react-native-reanimated react-native-worklets. In an Expo project, babel-preset-expo configures the worklets Babel plugin automatically — no babel.config.js step. Only a bare RN project without that preset adds the plugin manually, and there it must be last in the list. A missing or misplaced plugin doesn't silently fall back anymore — it throws Failed to create a worklet at runtime.
  • GestureHandlerRootView must wrap the app, or gestures do nothing with no error.
  • Reanimated 4 requires the New Architecture.
  • Expo Go is not a performance environment. Judge feel in a release build; a dev build's JS thread is slow enough to hide exactly the problems you're looking for.

120fps

On ProMotion iPhones, third-party animations are capped at 60fps unless CADisableMinimumFrameDurationOnPhone is set. Recent Expo SDKs set it by default — confirm it's there, and add it if not:

{ "expo": { "ios": { "infoPlist": { "CADisableMinimumFrameDurationOnPhone": true } } } }

Then the frame budget is 8ms, not 16. This is also why a UI-thread animation matters more on mobile than it does on web.

Recipes

For ready-to-build implementations — press feedback, drag-to-dismiss sheet, swipe-to-delete, collapsing header, list entrances, keyboard-synced UI, tab indicator, screen transitions — see RECIPES.md. Load it whenever the request matches one; start from the recipe rather than from a blank file.

Never Ship

NeverInstead
PanResponderGesture.Pan() from gesture-handler
setState in a gesture or scroll handlershared value + useAnimatedStyle
runOnJS (deprecated in Reanimated 4)scheduleOnRN from react-native-worklets
scheduleOnRN per frameonEnd, or useAnimatedReaction at a threshold
Reading or writing a shared value during render.get() / .set() in worklets, handlers, effects
Core Animated for anything a finger touchesReanimated
Animating height / width / margin / flex / toptransform + opacity (absolute, childless elements exempt)
Animating BlurView intensity or Android elevationcrossfade a static layer
entering on a virtualized list rowanimate the container, or itemLayoutAnimation
A screen transition rebuilt in JSnative stack animation
Sliding between tabsanimation: 'none'
Easing.in(...) on a UI elementEasing.bezier(0.23, 1, 0.32, 1)
scale(0) entrancescale(0.95) + opacity: 0
Distance-only dismissal thresholdvelocity or distance — a flick is enough
Hard stop at a boundaryrubber-band resistance
A haptic per frame, or as the only feedbackone per commit, always paired with a visual
Judging feel in Expo Go or the simulatorrelease build, slowest supported device

Output

Write the code. Then, in at most a few lines:

  • The gate result — frequency tier and named purpose. Say what you rejected and why.
  • The ingredients — tool, properties, spring or curve + duration, thread.
  • What to feel-check on device — gestures, velocity handoff and haptic timing cannot be judged from code. Name what to try: flick it, interrupt it mid-flight, reverse it, run it on the slowest Android you have.

The code is the deliverable. Don't pad it into a report.

Tone

Opinionated and brief. When the honest answer is "this shouldn't animate," or "this needs a real device before I can tell you if it's right," give it.

來自 emilkowalski 的更多技能

animate
emilkowalski
從零開始建立動畫,依序做出決定,以判斷整體是否自然流暢——是否該有動畫、目的為何、選用哪種工具、哪些屬性、哪條曲線與時長、如何打斷、如何結束。並撰寫實作內容。當被要求為某個東西加上動畫、增添動態感、讓元件更有生命力,或建立轉場效果時使用。若要評論現有動態效果,請使用 review-animations;若要審查整個程式碼庫,請使用 improve-animations。
animation-performance
emilkowalski
Keep web animations inside the frame budget — animate composite-only properties, keep motion off the main thread when the page is busy, and find the cause when an animation drops frames. Use when an animation is janky, choppy, stutters, or drops frames; when choosing which property to animate; when deciding between CSS and JS animation on performance grounds; or when reaching for `will-change` or GPU layers. For choosing easing, duration, or whether to animate at all use animate; for...
developmentdesign
animation-vocabulary
emilkowalski
反向查詢詞彙表,將模糊描述的網頁動畫或動態效果轉換為精確術語(例如:「彈出視窗開啟時的彈跳效果」→ Pop in;「iOS橡皮筋滾動」→ Rubber-banding)。適用於使用者詢問「那個叫什麼…」或描述某個動態效果卻不知其名稱,並希望獲得正確詞彙以提示AI或設計師時使用。此功能僅用於命名效果,而非設計或實作。
researchdesigncreative
apple-design
emilkowalski
Apple 的介面設計與流暢、物理動態方法,專為網頁轉譯。適用於建構或審查手勢驅動的 UI、彈性動畫、拖曳/滑動/面板互動、動量與可中斷轉場、半透明材質與深度、字體排印(光學尺寸、字距、行距)、減少動態效果,或 Apple 風格介面背後的設計基礎(回饋、空間一致性、克制)。
ask-emil
emilkowalski
Ask which skill or flow fits your situation. A router over the skills in this repo.
developmentproductivity
ask-sonner
emilkowalski
Sonner(React toast 函式庫)使用指南——安裝並接上 Toaster、選用正確的 toast() 呼叫、promise 與 loading toast、更新、關閉及持久化 toast、樣式、主題與圖示、定位與多個 toaster。適用於使用 Sonner 或排解其問題時——例如 toast 未出現、出現兩次、失去樣式、忽略 Tailwind 類別、位於 modal 後方,或未跟隨深色模式。
break-ui
emilkowalski
透過輸入最糟情況的資料來嘗試破壞 UI 元件——長名稱、無法換行的電子郵件、單字母名稱、缺少欄位、超大數量、零個項目、長標籤、非拉丁文字、表情符號、極端數字——接著在「Demo data / Worst case」切換開關後方呈現,並回報所有出問題的地方及各自的修正方式。當使用者要求對元件或畫面進行壓力測試、找出問題或邊界情況,或「試試最糟情況」時使用。若要進行視覺設計評論,請使用 emil-design-eng;若要處理動態效果……
testingdesigndevelopment
choreograph
emilkowalski
Coordinate several elements that animate together — decide what moves, in what order, how much they overlap, and what stays still — so a group reads as one intentional motion instead of a pile of separate animations. Use when building or fixing a staggered list, a hero entrance, a view swap inside a container, a multi-step flow, an element leaving while its siblings close the gap, a morph between rich states, or any interaction with several moving parts (icon + background + lines, panel +...
designdevelopment