Skip to main content
skill CX Codex

gestures — Claude Code skill for drag and swipe UI

gestures — a Claude Code skill for building and fixing drag, swipe, and sheet interactions. It activates on UI tasks where an element should follow a pointer and respond to release.

MIT 24,200 installs ★ 58,678 updated 2026-10-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add emilkowalski/skills --skill gestures -a claude-code
Open on GitHub

What gestures does

The skill covers gesture behavior for drawers, cards, toasts, and other draggable elements. While a pointer is down, the element should track it directly; once released, a spring can finish the movement using the gesture’s velocity. It also explains how to derive overlay opacity from sheet progress and keep a moving element interruptible.

For a bottom sheet or drawer, the skill recommends Vaul; custom gesture code is for interactions the library does not cover. Its Motion examples use useMotionValue, useTransform, and onDragEnd. CSS keyframes are ruled out for elements a gesture can touch, since they cannot be grabbed mid-animation.

What it helps with

  • keep a dragged element aligned with the pointer
  • dismiss a swipe based on distance or velocity
  • tie overlay opacity to sheet movement
  • let users redirect an element during its animation
  • return an element after a short drag

Example prompts for the agent

  • Fix the card swipe: it lags behind the finger and jumps on release.
  • Build a sheet that can be grabbed while closing.
  • Make a toast dismiss on a downward swipe, using the flick speed too.

How to install gestures

1Skills CLI (Vercel)

npx skills add emilkowalski/skills --skill gestures -a claude-code

2Manually: put the files in place

~/.claude/skills/gestures/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gestures/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gestures

How do I install gestures in Claude Code?

Run npx skills add emilkowalski/skills --skill gestures -a claude-code. The skill file is at ~/.claude/skills/gestures/SKILL.md.

What does gestures do?

It guides the agent through building and fixing drag, swipe, and sheet behavior. The guidance covers pointer tracking, release motion, and interruptible animations.

When does gestures recommend Vaul over a custom sheet gesture?

For a bottom sheet or drawer, it recommends Vaul. Custom gesture logic is for interactions the library does not cover.

Source text

SKILL.md · MIT
---
name: gestures
description: 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 props, rubber-band, pull to refresh, hold to delete, touch-action, "doesn't follow my finger", "jumps when I let go", "can't grab it mid-animation".
---

# 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](https://vaul.emilkowal.ski/)** — 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:

```jsx
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

```jsx
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:
  ```css
  [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 · MIT · emilkowalski/skills

Similar skills

SKILL.md skills catalog →
swiftui-gestures dpearson2699 swiftui-gestures guides gesture implementation in SwiftUI, from tap and drag recognition to multi-gesture composition and conflict handling. CX Codex +1 4,300installs framer-motion-gestures C-Jeril framer-motion-gestures — a Claude Code skill that teaches the agent gesture animation patterns in Framer Motion. Covers drag, pan, tap, hover, focus, and touch interactions. CX Codex +1 870installs hand-gestures abouchedidxcode The hand-gestures Claude Code skill adds hand-gesture controls to browser games and apps. The agent uses it for webcam tracking and gesture recognition on a web page. CX Codex +1 ★ 220repo stars find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs design-taste-frontend Leonxlnx The design-taste-frontend Claude Code skill sets design rules and checks for websites. It activates for new pages, redesigns, and requests to fix a generic-looking site. CX Codex +1 802,600installs grill-me Matt Pocock grill-me interviews you about a plan or design to expose gaps and sharpen decisions. Use it before implementation starts. CX Codex +1 1,424,476installs

From the same set19

The whole set →
animate-expo animate-expo — a skill for Claude Code that automates React Native and Expo animation builds. It selects implementation tools and methods based on UI thread performance requirements. CX Codex +1 189,400installs write-swift write-swift — a Swift skill for Claude Code guides code writing and review. It activates for Swift changes, migrations, and fixes involving concurrency, hangs, memory, or performance. CX Codex +1 169,400installs mobile-native mobile-native strips the tells that give a web app away on a phone: sticky hover, tap highlight flash, the 100vh bug. CX Codex +1 141,900installs break-ui Claude Code skill break-ui stress-tests user interfaces with realistic worst-case data and reports layout breaks. CX Codex +1 121,000installs animation-performance animation-performance — a skill for Claude Code that keeps web animations within the frame budget. It diagnoses causes of jank and frame drops, suggesting replacements for resource-heavy properties with composite-only ones. CX Codex +1 93,400installs remove-animations The remove-animations Claude Code skill removes animations that add no useful signal and scales back frequent motion with a purpose. It activates when asked to tone down movement or identify effects that make an app feel slow. CX Codex +1 47,000installs choreograph choreograph — a skill for Claude Code and other environments that groups separate interface elements into a single motion. Coordinates timing, order, and overlap to ensure a cohesive animation. CX Codex +1 32,800installs learn-taste learn-taste — a Claude Code skill turns design feedback into rules and records the reasoning behind them. It reviews session corrections and proposes which ones should carry into later work. CX Codex +1 13,700installs

Project sponsors

Companies that keep this analytics open