gestures
Build drag, swipe, and sheet interactions that track the finger 1:1 and stay interruptible
Install / Use
npx skills add emilkowalski/skills --skill gesturesInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of gestures
gestures scores 93/100 on our quality scale, 584th of 4,698 Development & Engineering skills we index (top 13%).
Its SKILL.md is 8.5 KB long, well organised into 14 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.
With 40,844 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so gestures is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-14. Automated pattern scan on 2026-11-14. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
gestures compared with similar skills
All 4 of these similar skills score higher than gestures; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| gestures (this skill)by emilkowalski | 93 | 40.8k | 54d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install gestures?
- Run
npx skills add emilkowalski/skills --skill gestures. The install tabs above show the steps for each supported agent. - Which AI agents does gestures work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is gestures safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is gestures still maintained?
- The repository was last updated about 2 months ago, so gestures is actively maintained.
Skill content
View source on GitHubname: 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 — 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 directtransformwrites), 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
transformdirectly 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; settingtransformon 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'sinfo.offsetandinfo.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
::beforehitbox instead of growing the layout. touch-actionon the drag axis (touch-action: pan-xfor 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.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
