to-spring-or-not-to-spring

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 {
  transition: 400ms cubic-bezier(0, 0.9, 0.1, 1);
}

Pass:

/* Fix slowness with shorter duration */
.element {
  transition: 200ms ease-out;
}

No Animation Rules

none-high-frequency

High-frequency interactions should have no animation.

Fail:

// Animated on every keystroke
function SearchInput() {
  return (
    <motion.div animate={{ scale: [1, 1.02, 1] }}>
      <input onChange={handleSearch} />
    </motion.div>
  );
}

Pass:

function SearchInput() {
  return <input onChange={handleSearch} />;
}

none-keyboard-navigation

Keyboard navigation should be instant, no animation.

Fail:

function Menu() {
  return items.map(item => (
    <motion.li
      whileFocus={{ scale: 1.05 }}
      transition={{ duration: 0.2 }}
    />
  ));
}

Pass:

function Menu() {
  return items.map(item => (
    <li className={styles.menuItem} /> // CSS :focus-visible only
  ));
}

none-context-menu-entrance

Context menus should not animate on entrance (exit only).

Fail:

<motion.div
  initial={{ opacity: 0, scale: 0.95 }}
  animate={{ opacity: 1, scale: 1 }}
  exit={{ opacity: 0 }}
/>

Pass:

<motion.div exit={{ opacity: 0, scale: 0.95 }} />

Output Format

When reviewing files, output findings as:

file:line - [rule-id] description of issue

Example:
components/drawer/index.tsx:45 - [spring-for-gestures] Drag interaction using easing instead of spring
components/modal/styles.module.css:23 - [easing-entrance-ease-out] Modal entrance using ease-in

Summary Table

After findings, output a summary:

| Rule | Count | Severity |

|------|-------|----------|

| spring-for-gestures | 2 | HIGH |

| easing-entrance-ease-out | 1 | MEDIUM |

| duration-max-300ms | 3 | MEDIUM |

Quick Reference

| Interaction | Timing | Type |

|-------------|--------|------|

| Drag release | Spring | stiffness: 500, damping: 30 |

| Button press | 150ms | ease |

| Modal enter | 200ms | ease-out |

| Modal exit | 150ms | ease-in |

| Page transition | 250ms | ease-in-out |

| Progress bar | varies | linear |

| Typing feedback | 0ms | none |

References

• Apple WWDC23: Animate with Springs ↗
• The Beauty of Bézier Curves - Freya Holmér ↗
• Motion library ↗