Imported from MrValraven/queer-pulse (.claude/skills/motion-react/SKILL.md). Install upstream with npx skills add MrValraven/queer-pulse --skill motion-react. Copyright stays with the author.

Motion for React (QueerPulse)

How to use the motion package (v11, imported from "motion/react") correctly in this repo. Motion is the JS-driven layer for the things CSS can't do well: drag, gestures, layout/FLIP animation, presence (enter/exit), spring physics, and scroll-linked motion. For entrances, hovers, skeletons, and scroll reveals, CSS + the repo primitives come first — that is the web-animation-best-practices skill's job. Reach for motion when the interaction is interactive or physical, not decorative.

The one rule that breaks everything if you miss it

This app wraps everything in <LazyMotion features={domMax} strict> (MotionProvider.tsx). That has two hard consequences:

1. Import m, never motion. strict THROWS on any motion.div/motion.*. Write <m.div>, <m.button>, etc. All the animation/gesture/layout/drag features you need are already loaded by domMax — you never call <motion.*>.
2. Reorder (Reorder.Group/Reorder.Item) is BANNED here. It is incompatible with LazyMotion: it pulls the full feature set into the main bundle and renders motion.* internally, so under strict it throws at runtime. It is not "a separate export that's exempt" — that is the single most common wrong belief about this codebase. Build reordering from m + drag + layout instead (recipe below).

Reduced motion — use the repo's flag, not motion's

import { useMotionPrefs } from "../../app/providers/MotionProvider";
const { reducedMotion } = useMotionPrefs();

Never use motion's own useReducedMotion() — it reads a module-cached value once and ignores the in-app "Reduce motion" toggle. useMotionPrefs() tracks the OS setting AND the toggle and re-renders on change. Gate the decoration, keep the function: a 1:1 finger-driven drag stays (it's a control); only its glide/lift animation is suppressed (transition={{ duration: 0 }}, drop whileDrag scale).

Tokens, not magic numbers

Motion takes JS numbers/arrays, so mirror styles/tokens/effects.css:

Entrances ease-out, 150–400ms. Springs are fine for drag/layout; avoid linear except continuous loops.

Quick reference

Full API with code examples: reference.md.

Canonical recipe: drag-to-reorder under strict

Live implementation: useRowDragReorder.ts

• EditorItemRow.tsx. The shape:

• Each row is an m.div with layout — Motion glides every row into its new slot on ANY reorder (a drag swap OR a keyboard-button move). transition={{ layout: reducedMotion ? { duration: 0 } : { duration: 0.25, ease: [0.22,0.68,0.16,1] } }}.
• Drive the drag with pointer events, NOT motion's drag gesture. A small hook arms on the grip's onPointerDown, then compares the pointer against sibling midpoints and does a single neighbour swap (jitter-free). The row is only ever at a discrete slot: the array reorders, layout glides. touch-action: none on the grip so touch drags instead of scrolling.
• Bind the move/up lifecycle to window, not the grip. Motion's per-frame layout re-projection during a drag drops the grip's pointer capture, so a pointerup on the grip is missed and the drag gets STUCK (row keeps following the cursor after release). Listening on window for pointermove/pointerup/pointercancel catches the release wherever it lands; add a event.buttons === 0 guard on move as a second belt.
• Why not motion's own drag for reordering: drag floats the row at an arbitrary offset that fights layout; combined with mid-drag array reordering it can leave a residual transform, so rows overlay/overlap even at rest. Reorder handles that reconciliation internally — but it's banned here. A discrete pointer-capture slot-swap sidesteps the whole class of bug. (Use motion's drag for free-floating gestures like swipe-to-dismiss, not for list reordering.)
• Every row needs position: relative (never static), with the dragged row on a higher z-index, so its lift/shadow paints above the gliding neighbours — Motion's layout transform spawns a stacking context a static row loses the z-fight against.
• Keep an explicit keyboard path (up/down arrow buttons): pointer drag is not keyboard-accessible and the a11y build gate blocks unlabeled/inaccessible controls. The grip stays aria-hidden; the buttons carry the i18n aria-label.

Repo conventions (non-negotiable)

• Grip/handles are react-icons, never glyphs (icons-not-glyphs): FiMoreVertical, MdDragIndicator.
• i18n every label (ns:-prefixed key, single-brace interp, EN + PT), no em dashes.
• Dual-mode: persisting a new order must branch demo vs live and PATCH the API in live mode.
• Bundle: don't add motion.* or Reorder; they defeat LazyMotion. Need a feature domMax lacks? Reconsider — it's a superset of drag+layout+gestures+animations.
• Update the Changelog (data + EN & PT) for user-facing motion changes.

Common mistakes

Red flags — stop

• You typed motion. anywhere → change to m.
• You reached for Reorder → it's banned here; build from m+drag+layout
• You called motion's useReducedMotion → use useMotionPrefs
• A drag interaction has no keyboard equivalent → add arrow-key/button path
• A duration or easing is a literal not traceable to a token → fix it