How to Implement Spring Animations with Traditional Physics Parameters in the Skills Repository

Spring animations with traditional physics parameters use mass, stiffness, and damping to create interruptible, natural motion that preserves velocity continuity, while high-level APIs abstract these into bounce and duration for easier implementation.

The Skills repository by Emil Kowalski establishes strict conventions for implementing spring animations with traditional physics parameters. In skills/review-animations/STANDARDS.md, the codebase defines canonical configurations that should be copied verbatim rather than approximated when building gesture-driven, interruptible interfaces.

Spring Configuration Types

The repository recognizes two distinct approaches to spring configuration, each serving different abstraction levels.

Traditional Physics (Low-Level)

The traditional physics approach exposes the underlying mechanical properties of the spring system. According to skills/review-animations/STANDARDS.md, the official configuration uses { type: "spring", mass: 1, stiffness: 100, damping: 10 }. These values provide fine-grained control over the spring's dynamics and are essential when working with lower-level animation libraries like spring-js.

Apple-Style (High-Level)

For teams using Motion or Framer Motion, the repository recommends the Apple-style abstraction: { type: "spring", duration: 0.5, bounce: 0.2 }. This high-level API maps internally to granular damping and response values used in iOS, making it a safe default for most UI work while remaining easy to reason about.

When to Use Spring Animations

Spring-based motion is the preferred technique for any UI interaction requiring interruptibility, velocity continuity, or a natural feel. The repository identifies three specific scenarios where spring animations with traditional physics parameters are mandatory:

• Gesture-driven motion – Dragging, swiping, or any interaction where users may reverse direction mid-gesture. Springs retain current velocity and retarget smoothly, avoiding the "brick-wall" effect of CSS keyframes as documented in skills/review-animations/STANDARDS.md.

• "Alive" UI elements – Components that continuously respond to user input, such as dynamic-island-style badges that react to touch without breaking continuity.

• Interruptible transitions – Toasts, toggles, or collapsible panels that can be added, removed, or reversed quickly without restarting animation from zero.

Core Physics Parameters Explained

Understanding the relationship between these parameters is crucial for implementing spring animations correctly:

Parameter	Meaning	Typical Range
mass	Inertia of the animated object; higher values produce slower starts.	1 (default)
stiffness	Spring tension controlling how snappy the animation feels.	100 (default)
damping	Controls overshoot; lower values create more bounce.	10 (default)
duration	Perceptual duration used in the high-level API.	0.5s
bounce	Amount of overshoot; keep between 0.1–0.3 for subtle UI effects.	0.2

As noted in skills/review-animations/STANDARDS.md, the Apple-style springs translate bounce and duration into the more granular physics values, bridging the gap between designer-friendly APIs and mechanical accuracy.

Implementation Workflow

Follow this sequence when implementing spring animations with traditional physics parameters in your projects:

1. Choose the appropriate API – Use the high-level config (duration + bounce) for Motion or Framer Motion implementations. For lower-level libraries like spring-js, pass the explicit mass, stiffness, and damping values.

2. Apply to dynamic interactions only – Reserve springs for gesture-driven values. Static fades or simple opacity changes should remain CSS transitions to avoid unnecessary computational overhead.

3. Fine-tune subtly – Maintain bounce between 0.1–0.3 for professional interfaces. Excessive overshoot should only appear in deliberately playful UI contexts.

4. Test interruptibility – Trigger the animation, then reverse it mid-flight. The element must continue from its current velocity rather than restarting from zero, confirming proper physics implementation.

Code Examples

High-Level Apple-Style Spring (Motion / Framer Motion)

import { motion } from "motion";

<motion.div
  animate={{ y: 0 }}
  transition={{ type: "spring", bounce: 0.2, duration: 0.5 }}
/>

Traditional Physics Spring (spring-js)

import { Spring } from "spring-js";

const spring = new Spring({
  mass: 1,
  stiffness: 100,
  damping: 10,
});

spring.to(targetY); // retargets from current velocity
element.style.transform = `translateY(${spring.currentValue}px)`;

Velocity Handling on Release (Framer Motion)

function handleDragEnd(event, info) {
  const velocity = info.velocity.y; // px/s
  animate(el, { y: 0 }, { type: "spring", velocity });
}

For deeper understanding of velocity preservation during retargeting, see the Apple design skill in skills/apple-design/SKILL.md, which explains how to translate release velocity into a spring's initial velocity. Additional practical examples using useSpring appear in skills/emil-design-eng/SKILL.md, while skills/animation-vocabulary/SKILL.md provides a comprehensive glossary of spring-related terminology.

Summary

• Spring animations with traditional physics parameters rely on mass, stiffness, and damping to create natural, interruptible motion.
• The Skills repository provides canonical configurations in skills/review-animations/STANDARDS.md that should be used verbatim.
• High-level APIs abstract physics into bounce and duration for easier implementation in Framer Motion.
• Always test interruptibility by reversing animations mid-flight to ensure velocity continuity.
• Reserve springs for gesture-driven interactions; use CSS transitions for static state changes.

Frequently Asked Questions

What is the difference between bounce/duration and mass/stiffness/damping?

Bounce and duration are designer-friendly abstractions that map to underlying physics values. Mass, stiffness, and damping are the actual mechanical parameters controlling the spring's behavior. The high-level API converts bounce: 0.2 and duration: 0.5 into specific damping and response values that simulate iOS-style physics, while the low-level API gives you direct control over the simulation.

When should I use springs instead of CSS transitions?

Use spring animations for any interaction that must remain interruptible or preserve velocity between state changes, such as drag gestures, swipeable cards, or dynamic toggles. CSS transitions are appropriate for static state changes like hover effects or page loads where the animation either completes fully or resets to start, lacking the physical continuity that springs provide.

How do I handle velocity when retargeting a spring animation?

Pass the current velocity directly to the spring configuration when initiating the new target. In Framer Motion, capture the velocity from the gesture info object (e.g., info.velocity.y) and include it in the transition options: { type: "spring", velocity: info.velocity.y }. This ensures the spring continues from its current momentum rather than restarting from zero, creating the natural "catch and release" feel documented in skills/apple-design/SKILL.md.

What are the default values for traditional physics springs in the Skills repository?

The canonical configuration specified in skills/review-animations/STANDARDS.md uses mass: 1, stiffness: 100, and damping: 10. These defaults provide a balanced, slightly underdamped spring suitable for most UI elements. For high-level implementations, the equivalent defaults are duration: 0.5 and bounce: 0.2.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}