Why MotionSpec reduces your token costs — and your hallucinations
Three mechanisms, no magic: the model emits a small declarative spec instead of animation code; a fail-closed validator rejects hallucinated APIs before they ship; and deterministic compilation makes the output cacheable. Each mechanism attacks a different place where LLM-generated UI burns money — generation length, debug loops, and regeneration. We deliberately publish no made-up percentages here: how much you save scales with how much motion your platform generates. The mechanisms, though, are inspectable — the core is MIT and on npm.
Mechanism 1: a spec is smaller than the code it replaces
When a model writes animation directly, it generates everything: keyframes, easing functions, timing math, the reduced-motion guard (usually forgotten), pause logic, vendor quirks, fallbacks. Hundreds of lines of output tokens — and every revision regenerates most of them. With MotionSpec, the model emits only intent:
{
"specVersion": "1.0",
"globals": { "respectReducedMotion": true },
"motions": [
{ "id": "hero-headline", "primitive": "scrollReveal",
"target": ".hero h1",
"params": { "from": { "opacity": 0, "y": 48 }, "duration": 0.8 },
"trigger": { "start": "top 80%", "once": true } },
{ "id": "cta-pulse", "primitive": "pulseLoop",
"target": ".hero .cta", "params": { "scale": 1.05, "duration": 2 } }
]
}
That is the entire generated artifact for two production animations — a couple dozen short lines. The implementation (guards, keyframes, budget enforcement) is compiled from the catalog of 40 verified primitives, not generated by the model at all. Those implementation tokens don't get cheaper; they disappear from the bill.
Mechanism 2: fail-closed validation ends the debug loop
Hallucination in animation code is rarely dramatic — it's a plausible easing name that doesn't exist, a method from a library version that never shipped, a primitive the model half-remembers. Generated code like that passes review and fails at runtime, and runtime failure means the expensive loop: reproduce, paste the error, regenerate, repeat. Each round costs a full context re-read plus regeneration.
A spec pipeline moves that failure forward. motion_validate checks every spec against the schema, the 40-primitive allow-list, parameter bounds and injection rules — fail-closed. A hallucinated primitive like teleportBlast, or a spin with an out-of-bounds 0.05s duration, is rejected in milliseconds with a precise, machine-readable error the agent can fix in a single, short round. You can watch the validator do exactly this in the browser playground — the error-laden examples are one click.
Mechanism 3: determinism makes motion cacheable
Ask a model the same question twice and you get two answers — which means N pages need N generations, and yesterday's hero animates differently from today's. A validated spec compiles deterministically: the same spec yields the same reviewed output, every time. Identical requests become cache hits instead of regenerations, output stays consistent across builds at any scale, and "it changed for no reason" stops being a ticket. Generation you don't repeat is the cheapest generation there is.
What this does not do
Honest scope: MotionSpec covers the motion layer. It does not stop a model from hallucinating in your business logic, your data layer, or your copy. And validation rejecting bad specs doesn't mean the model stops producing them — it means they can't reach production, and the correction loop happens at its cheapest possible point. For the defect classes this prevents in practice, see what is motion slop.
FAQ
Does MotionSpec eliminate hallucinations?
No tool can. It removes one whole class — hallucinated animation APIs and parameters — by making them unshippable, caught as precise pre-ship errors instead of runtime failures.
Where do the savings come from, concretely?
Shorter generations (spec vs. implementation), shorter failure loops (one validation round vs. runtime debugging), and cache hits (deterministic output). All three scale with your generation volume.
Do I need the MCP or the npm package?
The free, keyless MCP covers constraint and verification; the npm package adds the MIT compiler that ships the motion.
Is any of this measured?
Our published performance figures come from one pilot deployment under stated conditions, and we label them as such. Mechanisms above are structural and independently checkable in the open core.
Load the broken example in the playground and watch motion_validate reject it with the exact error an agent would receive.