To Spring or Not To Spring

Review animation code for correct timing function selection based on interaction type.

How It Works

1. Read the specified files (or prompt user for files/pattern)
2. Check against all rules below
3. Output findings in file:line format

Rule Categories

Priority	Category	Prefix
1	Spring Selection	spring-
2	Easing Selection	easing-
3	Duration	duration-
4	No Animation	none-

Decision Framework

Ask: Is this motion reacting to the user, or is the system speaking?

Motion Type	Best Choice	Why
User-driven (drag, flick, gesture)	Spring	Survives interruption, preserves velocity
System-driven (state change, feedback)	Easing	Clear start/end, predictable timing
Time representation (progress, loading)	Linear	1:1 relationship between time and progress
High-frequency (typing, fast toggles)	None	Animation adds noise, feels slower

Rules

Spring Selection Rules

spring-for-gestures

Gesture-driven motion (drag, flick, swipe) must use springs.

Fail:

<motion.div
  drag="x"
  transition={{ duration: 0.3, ease: "easeOut" }}
/>

Pass:

<motion.div
  drag="x"
  transition={{ type: "spring", stiffness: 500, damping: 30 }}
/>

spring-for-interruptible

Motion that can be interrupted must use springs.

Fail:

// User can click again mid-animation
<motion.div
  animate={{ x: isOpen ? 200 : 0 }}
  transition={{ duration: 0.3 }}
/>

Pass:

<motion.div
  animate={{ x: isOpen ? 200 : 0 }}
  transition={{ type: "spring", stiffness: 400, damping: 25 }}
/>

spring-preserves-velocity

When velocity matters, use springs to preserve input energy.

Fail:

// Fast flick and slow flick animate identically
onDragEnd={(e, info) => {
  animate(target, { x: 0 }, { duration: 0.3 });
}}

Pass:

// Fast flick moves faster than slow flick
onDragEnd={(e, info) => {
  animate(target, { x: 0 }, {
    type: "spring",
    velocity: info.velocity.x,
  });
}}

spring-params-balanced

Spring parameters must be balanced; avoid excessive oscillation.

Fail:

transition={{
  type: "spring",
  stiffness: 1000,
  damping: 5, // Too low - excessive bounce
}}

Pass:

transition={{
  type: "spring",
  stiffness: 500,
  damping: 30, // Balanced - settles quickly
}}

Easing Selection Rules

easing-for-state-change

System-initiated state changes should use easing curves.

Fail:

// Toast notification using spring
<motion.div
  animate={{ y: 0 }}
  transition={{ type: "spring" }}
/>
// Feels restless for a simple announcement

Pass:

<motion.div
  animate={{ y: 0 }}
  transition={{ duration: 0.2, ease: "easeOut" }}
/>

easing-entrance-ease-out

Entrances must use ease-out (arrive fast, settle gently).

Fail:

.modal-enter {
  animation-timing-function: ease-in;
}

Pass:

.modal-enter {
  animation-timing-function: ease-out;
}

easing-exit-ease-in

Exits must use ease-in (build momentum before departure).

Fail:

.modal-exit {
  animation-timing-function: ease-out;
}

Pass:

.modal-exit {
  animation-timing-function: ease-in;
}

easing-transition-ease-in-out

View/mode transitions use ease-in-out for neutral attention.

Pass:

.page-transition {
  animation-timing-function: ease-in-out;
}

easing-linear-only-progress

Linear easing only for progress bars and time representation.

Fail:

.card-slide {
  transition: transform 200ms linear; /* Mechanical feel */
}

Pass:

.progress-bar {
  transition: width 100ms linear; /* Honest time representation */
}

Duration Rules

duration-press-hover

Press and hover interactions: 120-180ms.

Fail:

.button:hover {
  transition: background-color 400ms;
}

Pass:

.button:hover {
  transition: background-color 150ms;
}

duration-small-state

Small state changes: 180-260ms.

Pass:

.toggle {
  transition: transform 200ms ease;
}

duration-max-300ms

User-initiated animations must not exceed 300ms.

Fail:

<motion.div transition={{ duration: 0.5 }} />

Pass:

<motion.div transition={{ duration: 0.25 }} />

duration-shorten-before-curve

If animation feels slow, shorten duration before adjusting curve.

Fail (common mistake):

/* Trying to fix slowness with sharper curve */
.element