ckissi/kinetics: 153 spring-physics micro-interactions for CSS and React

What Kinetics actually solves for interface engineers

Most CSS animation advice stops at transition: all 0.3s ease. That value is a fixed duration with a fixed curve, and it looks wrong the moment the distance or the starting velocity changes. A drawer that slides 40px and a drawer that slides 400px both take 0.3s, so the short one feels sluggish and the long one feels frantic. Spring physics inverts the problem: you describe stiffness, damping and mass, and the duration falls out of the simulation.

Kinetics is a catalogue of that approach applied to small interface moments. The README describes it as "a gallery of 153 spring-physics micro-interactions for web interfaces," and each entry ships with three things: a live demo, a physics-style parameter readout, and copy-paste CSS plus React code. The audience is a front-end engineer or designer who already knows what a button press should feel like and wants a starting parameter set instead of a blank keyframe block. It is not a runtime library you import. The repository is an Astro site whose build output is static, and the value is the patterns inside it.

How the gallery is put together

The layout is deliberately flat. src/pages/index.astro is the page shell: head, fonts, CSS links, scripts. All markup lives in src/content/body.html, which the README says is imported raw so that the embedded React snippets are not parsed as Astro expressions. That detail matters if you plan to fork the site, because it means the file containing 153 cards also contains braces, backticks and dollar-brace sequences that would otherwise break the Astro compiler.

Styling is split by concern across public/css: base, hero, gallery, effects-a, effects-b, effects-c and closing. Demo behaviour is wired by class name in public/js/main.js, and the header oscilloscope plus the interactive spring simulator live in public/js/physics-demo.js. So the data flow is: static HTML for structure, per-effect CSS files for the motion, and one JavaScript file that attaches listeners by class name. There is no component abstraction between the gallery and the effects. If you want effect number 87, you read its markup, its CSS rule and its handler, then copy the parts you need. That is the whole integration story, and it is a deliberate trade-off: less ceremony, more reading.

Installing Kinetics and opening your first effect

The README gives the development commands directly. There is no published package to install, so npm install pulls the Astro dependency from package.json and nothing else.

npm install
npm run dev      # http://localhost:4321
npm run build    # static output -> ./dist
npm run preview

The dev server listens on port 4321, which is Astro's default. Once it is running, the gallery renders every card with its live demo and a View code control. Opening a code panel shows the CSS and React samples for that effect; main.js handles the panel, the tabs and the copy button.

For a production build, npm run build writes a static site to ./dist and npm run preview serves that output locally so you can check it before deploying. If you only want one effect, you do not need any of this. Open the card, copy the CSS rule and the React snippet, and paste them into your own project. The gallery is a source of patterns, not a dependency you add to package.json.

The README also notes that Archivo, Inter and JetBrains Mono load from Google Fonts, and suggests self-hosting them for zero external requests. That is a real deployment consideration if you fork the site rather than just copying snippets.

Where the spring-physics framing stops being literal

The name promises simulation. The delivery is CSS and React snippets. Those are not the same thing. A CSS keyframe animation is a fixed timeline: the browser interpolates between declared stops over a declared duration. You can shape it with cubic-bezier so it overshoots and settles, and that reads as spring-like, but the curve does not respond to a changed distance or an interrupted gesture the way a solved spring equation does. If a user grabs a drawer mid-animation, the CSS version has to be cancelled and restarted; a real spring would carry the current velocity into the new target.

The README does not claim otherwise. It says the effects ship with a physics-style parameter readout, and the interactive spring simulator in physics-demo.js is presented as a header feature. So the honest reading is: Kinetics is a curated set of motion patterns whose parameters were chosen with spring thinking, expressed in the two formats most front-end codebases already accept. If you need velocity-preserving interruption, gesture-following motion, or a single source of truth for motion across a design system, you want a runtime spring library instead, and you should treat this gallery as reference material for tuning it.

There is a second limitation worth naming. The repository has no licence file among its top-level entries, and the README does not state terms. Until that is resolved, copying snippets into a commercial codebase is a decision you make without a stated grant, which is a different position from a project that ships an explicit permissive licence.

Kinetics compared with a runtime motion library

The obvious alternative is a JavaScript animation library that solves a spring at runtime, such as react-spring or Framer Motion. The difference is not quality, it is where the physics lives. With a runtime library, you declare a target and the library integrates the equation on every frame, so interruption, velocity handoff and dynamic targets all work because the state is continuous. You pay for that in bundle size, in a dependency you must keep upgraded, and in motion that is defined in JavaScript rather than in your stylesheet.

Kinetics takes the opposite position. The motion is precomputed into CSS and React samples that you paste and own. There is no runtime, no version to track, and no library that can break your animation on a major release. The cost is that the motion is frozen at the values the gallery chose, and adapting it to a different distance means editing the curve by hand. If your design system needs one motion language across dozens of components with interruption handling, the runtime library is the better fit. If you need a drawer, a toggle and a card hover that feel right, and you would rather not add a dependency for three animations, the gallery is the faster path.

Maintenance, upgrade cost and the missing licence

The last push to the default branch was on 2026-09-01, which is recent enough that the repository is not stale, but there are no retrieved releases, so there is no version history to reason about. In practice this matters less than it would for a library, because you are copying snippets rather than installing a package. An upstream change to a CSS rule does not reach your codebase unless you go looking for it. The upgrade cost is therefore near zero, and so is the benefit of upstream fixes: if a demo has a bug, you inherit it silently.

The dependency surface is small. package.json lists astro as the only dependency, and the scripts are the standard dev, start, build, preview and astro commands. If you fork the site itself rather than copying snippets, you are maintaining an Astro project with a body.html that holds all 153 cards in one file, which will get unwieldy if you add many of your own.

On licensing: the repository has no licence file in its top-level entries and the README does not state terms. That is not a legal opinion, just an observation about what is and is not declared. If you plan to ship these patterns in a product, the absence of a stated licence is something to resolve with the maintainer before you rely on it.

Editorial conclusion

Kinetics is worth adopting if you want to lift individual micro-interaction patterns into an existing interface and you are comfortable reading the CSS and React samples out of the gallery rather than installing a runtime. It is the wrong tool if you need a packaged component library with a versioned API, or if you need the motion to be driven by real spring simulation at runtime rather than by CSS easing curves that approximate one. Before you commit to anything, run npm run dev, open the effects that match your use case, and check two things in public/js/main.js: whether the demo behaviour you want is wired by class name in a way you can replicate, and whether the CSS sample for that card uses keyframes that your target browsers support.

Frequently asked questions

Official sources

1. ckissi/kinetics on GitHub
2. Issues
3. Project website
4. README