motion-web: a Claude Agent Skill for physics-driven creative web pages

What motion-web is, and the problem it is aimed at

Generated animation code has a recognisable failure mode. A model asked for a hover effect writes opacity: 0 to opacity: 1 over 300ms with a linear or ease curve, and the result reads as decoration. motion-web is a response to that. It is a Claude Agent Skill, meaning a folder of instructions and reference material that an agent loads before writing code, and its stated position is that motion is the core material of the interface rather than something applied afterwards. The README puts it as "动效即材质", motion is the material.

The audience is narrow and worth naming. This is for front-end engineers and agents producing a small number of showcase pages: a product launch, a portfolio, an interactive editorial piece. It is not a component library and not a framework. The repository ships seven complete cases, each a single HTML file that the README says runs standalone with no build tools and no external CDN dependencies. The skill is the instruction layer; the cases are the worked examples an agent can pattern-match against.

Spring-damper physics instead of easing curves

The mechanism is a set of explicit physics models rather than tween libraries. The README lists second-order spring-damper systems, anisotropic forces, stepped jitter and causal ecosystems, and forbids meaningless opacity fades and linear constant-speed easing. Each case is built on one of these models, and the case names are descriptive enough to read as a catalogue of techniques.

string-clock hangs softbody clock hands on elastic ropes but pins the tips with a stiff spring so the reading stays exact. The README frames the tension as the strokes lying while the time does not. ink-crowd pushes 620 capsule instances through a WebGL2 multi-render-target geometry and depth buffer, then draws ink contours only where depth is discontinuous, so the line work comes from the scene geometry rather than from an outline shader. char-curtain is 576 characters on 24 independent Verlet ropes with no horizontal constraint between columns, which is why a pointer sweep opens it like a curtain instead of stretching a mesh. lyre-crows clamps steering acceleration so the crows keep a turning radius while they chase words released by plucked strings.

That last detail is the useful signal. A turning-radius clamp is the kind of thing you add when you have watched the behaviour and found it wrong, not when you are inventing a demo.

Installing the skill and running a first case

Installation is a git clone into the skills directory. For Claude Code the README gives a path under ~/.claude/skills, and for Codex or Antigravity it gives ~/.agents/skills. There is no package manager step and no build.

git clone https://github.com/feitangyuan/motion-web.git ~/.claude/skills/motion-web

After that, the fastest way to see what the skill is talking about is the local gallery. The README serves the cases directory over Python's built-in HTTP server on port 8899.

python3 -m http.server 8899 -d cases/

Opening http://localhost:8899 should list the seven case pages. Each one is a single HTML file, so you can also open cases/string-clock/index.html directly in a browser without the server.

The verification step is the part worth doing before you trust anything. Each case has a dedicated flag on scripts/verify_case.py, and the script drives a headless Chromium through Playwright, simulating pointer sweeps, wheel events and inertia decay before asserting on displacement ratios, deformation error and rebound anchors.

python3 scripts/verify_case.py cases/string-clock/index.html --strings
python3 scripts/verify_case.py cases/ink-crowd/index.html --layer webgl --follow
python3 scripts/verify_case.py cases/char-curtain/index.html --min-shapes 1 --curtain

Expect a pass or fail result per case. If Chromium is not present, Playwright will need its browser download first; the README does not document that step, so treat a missing-browser error as an environment problem rather than a failing case.

The verification oracles are the actual product

Plenty of repositories ship pretty demos. What distinguishes this one is that the demos come with assertions attached, and the README is explicit that only code passing the mathematical checks is allowed to be delivered. The oracles are per-case rather than generic: --strings for the clock, --layer webgl --follow for the ink crowd, --stack for the sticky vinyl stack, --rail for the wheel-driven rail, and --min-shapes 1 combined with --flipbook, --curtain or --lyre for the remaining three.

This is a stronger claim than it first appears, and also a weaker one. It is strong because a headless probe that simulates real pointer and wheel input can catch dead interactions, the case where an element animates but nothing responds to the user. It is weaker because the assertions are written by the same author as the cases, so they encode that author's definition of correct damping and correct rebound. Passing --curtain tells you the curtain behaves within the tolerances someone chose. It does not tell you the tolerances are right for your project, and the README does not publish them. Read scripts/verify_case.py before you treat a pass as a quality guarantee.

Where motion-web is the wrong tool

The self-contained constraint cuts both ways. Because every case inlines subsetted fonts and draws with native WebGL2 or Canvas 2D, the pages run offline, which the README presents as a feature. The cost is that there is no shared runtime, no tree-shaking and no component reuse across cases. If your site has forty pages, copying a 600-instance ink renderer into each one is not a strategy.

The skill is also written for agents, not for humans browsing an API. There is no npm package, no TypeScript definitions and no documented programmatic entry point. The unit of work is a single HTML file, so integrating this into a React or Vue application means porting the physics by hand. The README does not document rollback, versioning or an upgrade path, and no releases were retrieved, so there is nothing to pin against.

Finally, the licence is a real constraint. The README badge states CC BY-NC 4.0 while the repository metadata reports NOASSERTION. A non-commercial licence rules out most client work, and the discrepancy between badge and metadata is worth resolving with the author before you build anything commercial on it.

How this differs from Framer Motion and GSAP

The obvious comparison is a declarative animation library such as Framer Motion, which is built for React component trees and gives you variants, layout animations and gesture props as part of a rendering model. motion-web inverts that. It targets vanilla JavaScript with no framework, and it does not give you an animation API at all. It gives you physics models to implement and a verification harness to check the implementation.

That difference matters at the point of integration. With Framer Motion you import a component and the library owns the interpolation. With motion-web you own the spring solver, and the value you get is the reference implementations and the oracle flags. The trade is real: less ergonomics, more control, and a test suite that can tell you a page is broken before a human looks at it. If your team already ships React and wants motion inside it, Framer Motion is the shorter path. If you are building a handful of standalone pages and want an agent to produce code that a script can reject, this is the more interesting shape.

Licence and the cost of keeping it working

The repository is not archived and the last push was on 2026-09-15, two days before this writing, so there is recent activity. There are no retrieved releases, which means no tags to pin and no changelog to read when something breaks. Upgrading means pulling from main.

On licensing, the README badge reads CC BY-NC 4.0 while the repository metadata says NOASSERTION. Those two do not agree, and the practical reading of a non-commercial clause is that commercial use needs a separate arrangement with the author. This is not legal advice; if you intend to ship this on a paid project, get the licence clarified in writing first. The maintenance cost is otherwise low, because there is no dependency tree to update. The cases are static HTML, and the only moving part is the Playwright and Chromium toolchain behind verify_case.py.

Editorial conclusion

Adopt motion-web if you are building a small number of high-touch marketing or portfolio pages and you want an agent to produce code that a script can reject. Skip it if you need a component library, TypeScript types, npm distribution, or a permissive licence for commercial client work, because the README badges CC BY-NC 4.0 and the repository carries a NOASSERTION licence field. Before using it, clone the repository, run one verifier such as python3 scripts/verify_case.py cases/string-clock/index.html --strings, and confirm Playwright and Chromium install cleanly on your machine.

Frequently asked questions

Official sources

1. feitangyuan/motion-web on GitHub
2. Issues
3. README