gestures

작성자: emilkowalski

Build drag, swipe, and sheet interactions that track the finger 1:1 and stay interruptible. Use when building or fixing anything the user drags, swipes, flings, holds, or dismisses with a gesture — drawers, sheets, swipe-to-dismiss toasts and cards, drag-to-reorder, pull-to-refresh, hold-to-confirm — or when a gesture feels laggy, disconnected from the finger, jumps on release, or can't be caught mid-animation. Triggers on — gesture, drag, swipe, fling, sheet, snap points, Vaul, Motion drag...

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

Gesture-Driven UI

How to build gestures that feel physical. A gesture is direct manipulation: while the finger is down, the UI is the finger; the moment it lifts, physics takes over. Every rule below follows from that split.

First decision: build it, or use a solution that exists?

Doing a drawer gesture right means momentum-based dragging, overlay opacity matched to drag progress, velocity-aware dismissal, focus trapping, and Escape-to-close. That is weeks of edge cases, not an afternoon. For a bottom sheet / drawer, default to Vaul — it exists precisely because this is hard to hand-roll. Build the gesture yourself only when no library covers the interaction (custom swipe cards, bespoke drag interactions). When unsure, read ../pick-ui-library/SKILL.md.

The two phases of every gesture

Walk this split for any gesture you build. Mixing the phases up is the #1 cause of gestures that feel wrong.

Is the pointer currently down?
├── Yes → TRACK phase: position maps 1:1 to the pointer.
│         No easing. No duration. No spring. The element IS the finger.
└── No  → RELEASE phase: physics finishes the motion.
          A spring seeded with the release velocity, or a CSS transition
          when the component is CSS-only (Vaul, hold-to-confirm). Never a keyframe.

Track phase rules

  • 1:1 means 1:1. Drive position from a useMotionValue (or direct transform writes), never a spring or a transition — a spring during tracking makes the element trail the finger and feel disconnected, like dragging something through syrup.
  • Write transform directly on the dragged element. Never update a CSS variable on a parent to move children: CSS variables are inheritable, so every change recalculates styles for all descendants. This exact bug made Vaul's drag laggy past ~20 list items; setting transform on the element fixed it.
  • No React state per move event. A re-render every pointermove drops frames. Motion values and direct style writes bypass the render cycle.
  • Rubber-band at the edges. Dragging past a boundary should move the element a fraction of the distance (Motion: dragElastic ≈ 0.2), not stop dead — hard stops feel like hitting a wall; resistance communicates "there's nothing further" physically.

Release phase rules

  • Custom drags finish with a spring, seeded with the gesture's velocity. The element should leave the finger at the speed it was moving. A fixed-duration ease here makes every fling land identically, which reads as fake.
  • Dismiss on distance OR velocity. Passing a distance threshold (~40–50% of travel) dismisses, but so does a fast flick over a short distance. In Motion, read both from onDragEnd's info.offset and info.velocity. Distance-only thresholds make flicks feel ignored.
  • Bounce belongs only at the end of a drag. A drag applies force — like throwing a ball at a wall — so a slight bounce on release feels physical. The same element closed by a button press gets zero bounce: no force was applied. Keep bounce at 0.1–0.3, and remember bounce scales inversely with element size (smaller elements need more bounce to read the same).
  • Snap-back is fast. If the gesture doesn't pass the threshold, return quickly with the spring — a slow snap-back feels like the UI is disagreeing with the user in slow motion.

Interruptibility is non-negotiable

The user must be able to catch a sheet mid-close and drag it back. Springs allow this: when retargeted mid-flight they keep their current velocity, so the redirect is seamless. CSS @keyframes restart from zero and cannot be caught — this is why Sonner's early CSS enter animation made toasts jump when a second toast arrived. Never use a keyframe animation on anything a gesture can touch. CSS transitions and springs only.

Linked values

The dragged element is rarely alone — an overlay fades, the page behind scales. Derive these from drag progress, don't animate them separately:

const y = useMotionValue(0);
const overlayOpacity = useTransform(y, [0, drawerHeight], [1, 0]);

One source of truth means the overlay is always exactly as faded as the drawer is dismissed — including mid-gesture, including when the user reverses. Two separate animations drift apart the moment a gesture is interrupted.

Motion drag props

const y = useMotionValue(0);

<motion.div
  drag="y"
  style={{ y }}
  dragConstraints={{ top: 0 }}
  dragElastic={0.2}
  dragMomentum={false}
  onDragEnd={(e, info) => {
    if (info.offset.y > threshold || info.velocity.y > 500) dismiss();
    else animate(y, 0, { type: 'spring', duration: 0.5, bounce: 0.2, velocity: info.velocity.y });
  }}
/>

dragMomentum is on by default — right for a flung card, wrong for a simple reposition; disable it when the element should stop where the finger stops. The example above disables it because onDragEnd hands the release to its own spring. dragConstraints takes a ref or bounds object.

Sheets without springs: the Vaul curve

Vaul mimics the iOS sheet with pure CSS to stay small: cubic-bezier(0.32, 0.72, 0, 1) over 500ms. The curve is extremely steep at the start — that's what lets a 500ms duration still feel snappy while landing with a spring-like gentle settle. Two rules from it:

  • A small floating drawer (not touching the screen edge) should override to ~200ms — the 500ms iOS timing only reads right on a full-width edge-attached sheet:
    [data-vaul-drawer]  { transition: transform 0.2s cubic-bezier(0.165, 0.84, 0.44, 1); }
    [data-vaul-overlay] { transition: opacity  0.2s cubic-bezier(0.165, 0.84, 0.44, 1); }
    
  • The component must feel like a single entity. If the drawer opens in 200ms, its height changes and content crossfades must live in the same timing family — one slow sub-animation makes the whole thing feel broken.

Mark interactive children with data-vaul-no-drag so pressing a button inside the drawer doesn't start a drag.

Spatial consistency

An element dismisses in the direction it entered. Sonner's toast slides up from the bottom, so swipe-down dismisses it — enter and exit share one axis, which is what makes the gesture feel discoverable and intuitive without instruction. A gesture that dismisses along an axis the element never moved on has to be learned; one that reverses the entrance is felt.

Hold gestures are asymmetric

Hold-to-delete and similar press-and-hold interactions use linear during the hold — the animation visualizes time passing, and time passes linearly; any other curve lies about how long is left. On release before completion, snap back fast with ease-out. The deliberate phase is slow and honest; the cancel is instant. Symmetric timing here is a bug.

Touch checklist

Run through this for every gesture you ship:

  • Test on a real phone — hit the dev server by local IP. Trackpad simulation lies about touch, and a 60Hz desktop monitor hides opacity-transition roughness that a 120Hz phone shows.
  • Hit targets ≥ 44×44px. Enlarge small visual targets with an invisible ::before hitbox instead of growing the layout.
  • touch-action on the drag axis (touch-action: pan-x for a vertical drag, etc.) so the browser doesn't fight the gesture with native scrolling.
  • Gate hover effects behind @media (hover: hover) and (pointer: fine) — touch fires phantom hovers on tap.

Reduced motion

Tracking is direct manipulation — the user is producing the motion — so it stays. What reduces: momentum flings, bounce, and any decorative motion around the gesture. On release under prefers-reduced-motion, settle with a short opacity/position change instead of a bouncy spring.

When it still feels wrong

A "weird" spring is usually fixed by increasing damping. A gesture that stutters is a performance problem — check the track-phase rules above first, then use the animation-performance skill. To diagnose a feeling you can't name, record the gesture and scrub it frame by frame.

emilkowalski의 다른 스킬

animate
emilkowalski
애니메이션을 처음부터 구축하되, 그것이 자연스럽게 느껴지는지를 결정하는 순서대로 판단을 내린다 — 애니메이션을 적용할지 여부, 목적, 도구, 속성, 곡선과 지속 시간, 인터럽트 방식, 종료 방식을 결정한다. 구현을 작성한다. 무언가를 애니메이션으로 만들고, 모션을 추가하고, 컴포넌트에 생동감을 부여하거나, 전환을 구축하라는 요청이 있을 때 사용한다. 기존 모션을 비평할 때는 review-animations를 사용하고, 전체 코드베이스를 감사할 때는 improve-animations를 사용한다.
animate-expo
emilkowalski
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For...
developmentdesign
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 토스트 라이브러리) 사용 가이드 — Toaster 설치 및 연결, 올바른 toast() 호출 선택, promise 및 로딩 토스트, 토스트 업데이트·해제·유지, 스타일링, 테마 및 아이콘, 위치 지정 및 다중 toaster 설정. Sonner로 작업하거나 문제를 해결할 때 사용 — 토스트가 표시되지 않거나, 두 번 표시되거나, 스타일이 사라지거나, Tailwind 클래스를 무시하거나, 모달 뒤에 위치하거나, 다크 모드를 따르지 않는 경우.
break-ui
emilkowalski
Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion...
testingdesigndevelopment