How to Configure Spring Animations Using Traditional Physics Parameters in Motion

Spring animations using mass, stiffness, and damping give you precise control over UI motion by directly manipulating physical properties rather than relying on higher-level timing abstractions.

In the emilkowalski/skills repository, the Motion (formerly Framer Motion) library supports two distinct configuration styles: Apple-style springs (duration + bounce) and traditional physics springs (mass + stiffness + damping). This guide focuses on the latter—when you need granular control over how an element settles into place.

Core Physics Parameters

The three parameters that define a traditional physics spring are:

Parameter	Physical Meaning	Typical Value in Repository
mass	Inertia of the animated object—higher values feel heavier and slower	1 (default)
stiffness	Force pulling toward the target—higher values produce snappier motion	100
damping	Resistance that kills oscillations—lower values create more bounce	10

These values appear together in skills/animate/SKILL.md as the canonical traditional-physics example:

{
  type: "spring",
  mass: 1,
  stiffness: 100,
  damping: 10
}

According to the source at skills/animate/SKILL.md#L129-L130, this configuration produces a critically damped spring—smooth settling without overshoot.

Traditional Physics vs. Apple-Style Springs

The repository treats both approaches as first-class configurations, but they serve different purposes.

Traditional physics (mass / stiffness / damping) excels when you need to tune the feel of an interaction. Designers can independently adjust:

• How heavy the object feels (mass)
• How aggressively it snaps to target (stiffness)
• How quickly it stops oscillating (damping)

Apple-style (duration / bounce) trades expressiveness for predictability. As noted in skills/review-animations/STANDARDS.md#L67-L70, Apple-style configurations use duration: 0.5 and bounce values to match platform conventions without requiring physics intuition.

Choose traditional physics when gesture-driven elements need customized settling behavior; prefer Apple-style for standard transitions that must align with system conventions.

Basic Traditional Physics Configuration

Here's the standard implementation following repository conventions:

import { motion } from "motion";

motion(
  element,
  { y: targetY, opacity: 1 },
  {
    type: "spring",
    mass: 1,
    stiffness: 100,
    damping: 10
  }
);

Notice that duration is omitted—the animation length emerges naturally from the physics values. A stiffer spring with lighter mass completes faster; heavier mass or higher damping extends the settle time.

Handling Gesture Release Velocity

For interruptible, momentum-preserving animations, pass the gesture velocity directly to the spring configuration. The skills/apple-design/SKILL.md#L104-L110 section demonstrates this pattern for drag gestures:

function onDragEnd(event, info) {
  const velocityY = info.velocity.y; // pixels per second from pointer

  motion(
    element,
    { y: snapTargetY },
    {
      type: "spring",
      mass: 1,
      stiffness: 100,
      damping: 10,
      velocity: velocityY // preserves throw momentum
    }
  );
}

The velocity parameter accepts raw pixel-per-second values from Motion's gesture system. Without this, the spring restarts from zero velocity, breaking the illusion of physical continuity.

Tuning Parameters for Different Feels

Adjust the three core parameters to achieve specific motion characteristics:

• Heavy, sluggish feel: Increase mass to 2 or higher
• Snappy, responsive snap: Increase stiffness to 300+
• Bouncy, playful settling: Decrease damping to 5 or below
• Smooth, professional stop: Keep damping near 10 for critical damping

The skills/animation-vocabulary/SKILL.md#L126-L132 glossary defines these terms for cross-functional teams, ensuring designers and developers share the same mental model.

Enforcing Consistency via Repository Standards

The skills/review-animations/STANDARDS.md#L67-L70 file contains authoritative tables of approved spring configurations. The skills/improve-animations/AUDIT.md#L65-L66 rules require reviewers to pull exact values from these tables rather than inventing custom numbers.

When submitting code, reference the specific standard you're following:

// Matches skills/review-animations/STANDARDS.md physics-style #1
const springConfig = {
  type: "spring",
  mass: 1,
  stiffness: 100,
  damping: 10
};

This practice guarantees that all spring animations in the codebase feel coherent and maintainable.

Complete Responsive Example

Here's a pattern that switches between physics styles based on design tokens:

import { motion } from "motion";

interface SpringOptions {
  isPlayful: boolean;
  gestureVelocity?: number;
}

function animateToTarget(
  element: Element,
  target: { x: number; y: number },
  options: SpringOptions
) {
  const { isPlayful, gestureVelocity = 0 } = options;

  const config = isPlayful
    ? { type: "spring" as const, duration: 0.5, bounce: 0.2 }
    : { type: "spring" as const, mass: 1, stiffness: 100, damping: 10 };

  motion(element, target, {
    ...config,
    ...(gestureVelocity !== 0 && { velocity: gestureVelocity })
  });
}

This mirrors the conditional pattern shown in skills/animate/SKILL.md, accommodating both precise tool interactions and playful marketing moments within the same component.

Summary

• Use mass, stiffness, and damping when you need fine-grained control over spring behavior
• Reference STANDARDS.md for approved parameter combinations rather than guessing values
• Pass velocity from gestures to maintain momentum across animation interruptions
• Omit duration for physics springs—the settle time derives naturally from the parameters
• Document your config source in code comments to satisfy audit requirements

Frequently Asked Questions

What happens if I specify both duration and physics parameters?

Motion prioritizes the physics model when mass, stiffness, or damping are present, ignoring duration. For time-based control, switch to Apple-style configuration with duration and bounce instead.

How do I convert between Apple-style and traditional physics values?

The repository does not provide automatic conversion—STANDARDS.md maintains separate tables for each style. As a rule of thumb, duration: 0.5, bounce: 0 approximates mass: 1, stiffness: 100, damping: 10, but subtle differences in feel remain.

Can I animate stiffness or damping mid-animation?

No—Motion evaluates spring parameters once at animation start. For dynamic behavior, interrupt the current animation with a new motion() call using updated parameters and the current velocity.

Why does my spring feel different on 120Hz displays?

Motion's physics solver uses wall-clock time, so the same parameters produce consistent settle durations regardless of refresh rate. If perception differs, verify that you're not inadvertently scaling time elsewhere in your animation pipeline.

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