@opsinjs/motion

Overview

opsinjs expresses springs as CSS. A spring is defined by its physical parameters and then sampled into a linear() easing with enough stops that the browser can run it on the compositor with no JavaScript, no animation library, and no main-thread work. Those parameters are stiffness, damping and mass.

That sampling is arithmetic, and it is the arithmetic this package exposes. The reasoning behind the approach is Springs as tokens; this page is the callable form.

Nothing is published. The implementation lives in this repository and produces the spring tokens in app/globals.css today.

The proposed API

// PROPOSED. Not implemented. Subject to change without a deprecation cycle.

export interface Spring {
  stiffness: number
  damping: number
  mass?: number        // default 1
}

/** Sample a spring into a CSS linear() easing. */
export function toLinear(spring: Spring, options?: {
  stops?: number       // default chosen for smoothness against stylesheet size
  epsilon?: number     // settle threshold
}): string

/** How long the spring takes to settle, in milliseconds. */
export function settleTime(spring: Spring, epsilon?: number): number

/** Position at time t, for plotting a curve. */
export function sample(spring: Spring, t: number): number

/** The reduced-motion form of any easing: instantaneous, still a state change. */
export function reduced(easing: string): string

Why a spring and not a Bézier

A cubic Bézier is defined by how it looks. A spring is defined by how it behaves.

For interface motion the difference shows up when something is interrupted. A Bézier being replayed from a new position restarts its shape and produces a visible jolt; a spring has velocity and continues from wherever it was. In a health app the interruptible cases are the ones that matter. Examples are a value updating while a sheet is still opening, and a status changing while its pill is animating.

The trade is that a spring cannot be typed into a stylesheet by hand. linear() is the bridge: the browser gets a plain easing function it can run cheaply, and the source of truth stays the physical parameters. This is the same reason the tokens are generated rather than authored.

The reduced-motion contract

reduced() encodes a rule the CSS already implements:

@media (prefers-reduced-motion: reduce) {
  :root {
    --opsin-duration-base: 1ms;
    --opsin-ease-spring: linear(0, 1);
  }
}

A state change still happens. It simply happens at once. Durations collapse to 1ms rather than to zero, so transition events still fire and code that waits for them does not hang. Springs collapse to linear(0, 1). Opacity cross-fades are kept, because they do not move; translation and scale are what cause trouble.

This is a contract rather than a preference, and stating it as a function makes it testable. The observable version is <MotionDemo> on Reduced motion, where the fallback can be watched rather than described.

What it is intended for

What it deliberately will not do

It is not an animation library. It does not run animations, does not manage state, does not orchestrate sequences, and has no React surface. It produces strings and numbers that CSS consumes.

That boundary is what keeps opsinjs' motion running on the compositor. A package that animated things would pull a runtime into every product that imported it, and the whole argument for linear() is that no runtime is needed.

Verify it worked

Troubleshooting

npm install @opsinjs/motion fails. Nothing is published yet.

My linear() string is enormous. Too many stops. There is a point past which extra stops are imperceptible and merely make the stylesheet unreadable and undiffable.

The animation looks wrong in Safari. Check linear() support against the tested floor on Browser support; the documented degradation is a plain easing, not no animation.

Prettier reformatted my spring token one stop per line. That is why app/globals.css is in .prettierignore. Keep generated easings out of the formatter's path.

Next

• Springs as tokens is the reasoning.
• Reduced motion is the contract, observable.
• Motion in health UI says when not to animate at all.