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

> Learn how to implement spring animations using traditional physics parameters like mass stiffness and damping. Create natural motion with Emil Kowalski's skills repository.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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)

```tsx
import { motion } from "motion";

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

```

### Traditional Physics Spring (spring-js)

```tsx
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)

```js
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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md), while [`skills/animation-vocabulary/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`.