# MasterPlayspots/motionspec [Health: Active]
**Category:** π» Developer Tools
**Repository:** https://github.com/MasterPlayspots/motionspec
**GitHub Stars:** 0
**npm Downloads (last month):** 661
**Views:** 1
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/masterplayspots-motionspec
## Description
Reduced-motion / WCAG 2.2.2+2.3.3 verification for web animation: agents author validated specs; a deterministic compiler emits reduced-motion-safe, on-budget CSS. Keyless hosted endpoint (motioncatalog, motionvalidate).
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"motionspec": {
"command": "npx",
"args": ["-y","motionspec"]
}
}
```
## Documentation & README
# MotionSpec
[](https://www.npmjs.com/package/motionspec)
[](https://www.npmjs.com/package/motionspec)
[](./LICENSE)
[](https://smithery.ai/servers/kevin-froeba/motionspec)
**MotionSpec is an open-core trust layer that checks and compiles reduced-motion-safe, on-budget UI animation for AI-generated web apps.** An LLM authors a **schema-validated JSON spec**; a **deterministic compiler** emits vanilla-GSAP JavaScript + CSS β injection-proof and catalog-validated *by construction*, with an enforced `prefers-reduced-motion` fallback and a performance budget, with WCAG 2.2.2 (Pause, Stop, Hide) pause-path candidates reported β reduced-motion guards map to WCAG 2.3.3 (Animation from Interactions), Level AAA.
Run it two ways: as a keyless **MCP server** any LLM host can call (`npx motionspec`), or as a **CLI compiler** in your build (`motion compile spec.json`). Either way you keep plain files: vanilla-GSAP JavaScript plus CSS. (A WAAPI/CSS lowering exists in the codebase, but it has no CLI flag, no MCP tool and no schema target yet β see [below](#one-build-target-one-internal-lowering).) MIT core. Docs: https://motionspec.dev
The thesis: **capability lives in the catalog, not the model.** A bigger model can write more elaborate specs, but it can never emit a primitive, parameter, or selector the Trust Boundary hasn't approved. The compiler trusts only what passes.
```
request ββ> Routing (small model, Stage A) ββ> MotionSpec (JSON)
β cache Β· 1 repair-retry Β· escalation β
βΌ βΌ
telemetry TRUST BOUNDARY (fail-closed)
β
βββββββββββββββ΄ββββββββββββββ
βΌ βΌ
Compiler (no model, Stage B) WAAPI lowering (internal β no CLI/MCP path yet)
β β
out/*.motion.js + .css Element.animate / IO / @keyframes
```
### Not to be confused with
> **Not to be confused with:** the Android Material Components `MotionSpec` class, the iOS material-motion `MotionSpec`, Motion.dev / Framer Motion, the usemotion.com calendar app, the Motion Specialties mobility brand, or text-to-video generators (Runway/Sora/Kling/Viggle). MotionSpec checks the *UI animation inside web apps* β it does not generate video.
## 60-second start
```bash
npx motionspec # stdio MCP server β no install needed
claude mcp add motionspec -- npx motionspec # register in Claude Code / any MCP host
npm install -g motionspec # or take the CLI:
motion compile spec.json # deterministic build β ./out in your cwd
```
The host LLM authors the spec; the Trust Boundary stays enforced either way. Listed on the MCP Registry as `io.github.MasterPlayspots/motionspec`. A hosted MCP endpoint is live: keyless `motion_catalog` + `motion_validate` at `https://api.motionspec.dev/mcp` (streamable-http; keyed tiers cover compile/audit/stats) β setup: https://motionspec.dev/docs.
### Claude Code plugin
This repo is also a Claude Code plugin: it bundles the MCP server (`npx motionspec`, all five tools, local, keyless) with two skills β `/motionspec:motion` (the authorβvalidateβcompile workflow) and `/motionspec:audit ` (motion-accessibility check, WCAG 2.2.2/2.3.3). Try it directly from a clone with `claude --plugin-dir .`, or install it from the community marketplace once listed:
```bash
/plugin marketplace add anthropics/claude-plugins-community
/plugin install motionspec@claude-community
```
## Status
| | |
|---|---|
| Version | **v1.2.7** Β· schema frozen at spec v1 (ADR-0001, signed) |
| Published | **npm `motionspec`** (82 kB packed, 67 files, nothing dev-only ships) Β· MCP Registry |
| Tests | **302 green** β injection attacks, 6000-spec fuzz, golden determinism, schema parity, pause-controls, motion-a11y audit Β· CI on Node 18/20/22 + x86 Playwright e2e |
| Catalog | **40 primitives**, every one device-verified, reduced-motion-fallback mandatory; the 18 continuous loops also carry a WCAG-2.2.2 pause path |
| Supply chain | **2 runtime deps** (MCP SDK, zod β both pinned) Β· 0 vulnerabilities Β· CycloneDX SBOM committed Β· all permissive licenses Β· CI actions SHA-pinned |
| Coverage | 99.06% lines / 99.09% functions / 79.05% branches of `src/` (`npm run coverage`, 2026-09-04; CI gate 90/90/75) |
| Last audit | 2026-07-03 β 17/17 integration handshakes evidenced, infra 8.1/10, security: **0 critical**, full-git-history secret scan clean |
| First client | CHS Computer β live on Vercel |
| Hosted MCP | **live** β keyless `motion_catalog`/`motion_validate` at api.motionspec.dev/mcp Β· keyed tier: Cloudflare Worker, per-key gated (hashed keys in KV) Β· two-stage rate limiting (pre-auth per IP + per key, burst-verified) Β· per-minute cron canary + external heartbeat (synthetic fault β alert in <5 min, proven on real infra) Β· Analytics Engine telemetry, PII-scrubbed Β· gated `/dashboard` |
Schema v1 is frozen: `specVersion "1.0"` is the stable public contract; `"0.1"` is deprecated and accepted until v1.2 (a tripwire test enforces the revisit). The `[MS-XXX]` error-code registry is public API β codes are never reused or redefined.
## What the compiler guarantees
1. **Allow-list** β a primitive not in the catalog never reaches the compiler.
2. **Injection-proof** β ids, selectors, string params and triggers are charset-validated; every interpolation is a JS literal (`JSON.stringify`) or a CSS-screened raw value through one shared safety gate (`safety.js`). Malicious model output is rejected fail-closed β tested and fuzzed over 6000 random specs.
3. **a11y by construction (motion)** β safe defaults, enforced gates, and proof per build. `respectReducedMotion` is **default-on at the compiler level** (fail-safe): omitting it still yields a `prefers-reduced-motion` guard. Opting out is possible but emits `MS-GLOBALS-RRM-OFF`; a prompt-side instruction alone can never disable the guard.
4. **Pause/Stop for loops (WCAG 2.2.2)** β every continuous loop primitive is tagged `a11y.persistent`, and the compiler emits a pause path **by construction**: an `animation-play-state: paused` rule keyed on `html[data-ms-paused]` (outside the reduced-motion guard, so it is always live) plus, under `pauseControls: "auto"` (the fail-safe default), one accessible pause/stop toggle (`type="button"`, `aria-pressed` in sync, β₯24 px target, visible focus ring, not rendered under reduced motion). `pauseControls: "api"` keeps the CSS contract and leaves the control to the integrator; `"off"` opts out but emits `MS-GLOBALS-PAUSE-OFF` when a persistent motion is present. The promote-gate refuses any `infinite`/`repeat:-1` primitive that is not `a11y.persistent`. A spec with no loops adds **zero** extra bytes.
5. **Determinism** β same spec β byte-identical code (golden-file tests for the GSAP output and for the internal WAAPI lowering).
6. **Versioned** β schema frozen v1; catalog SemVer enforced by a diff-gate (a tightened bound shipped as a "patch" fails CI); specs may pin `catalogVersion` for reproducibility (`MS-CATALOG-PIN-MISMATCH` fail-closed).
7. **Observability** β every request logs `model | model-repaired | cache-hit | escalate-*` (local: JSONL sink Β· hosted: Cloudflare Analytics Engine, PII-scrubbed). Escalation clusters are the growth signal for new primitives.
## One build target, one internal lowering
What you can get out of the compiler today, through the CLI or the MCP tools, is exactly one target:
- **`vanilla-gsap`** β GSAP + ScrollTrigger. `meta.target` accepts nothing else (schema frozen at v1).
A second lowering exists in the codebase and is kept green by the test suite, but it is **not reachable** through any interface:
- **WAAPI/CSS lowering** (`src/compiler/lower-waapi.js`) β zero-GSAP output on `Element.animate`, IntersectionObserver, and `@keyframes`/`position: sticky`. Full catalog coverage, byte-identical golden per primitive, same accessibility guard, same CSS safety gate. This is the framework-decoupling hedge: the IR outlives any animation library. **Internal** β referenced only by the tests and `bin/promote-gate.js`; there is no CLI flag, no MCP tool and no schema target for it (ADR-0001 freezes `meta.target` to `vanilla-gsap`; engine wiring is out of scope, ADR-0002). Do not plan a build on it until a release note says otherwise.
## The catalog grows itself β humans keep the taste
The **Catalog Forge** (CI workflow, manual dispatch) picks the top telemetry-ranked gap, generates *one* candidate primitive, drives it through a multi-stage gauntlet β meta-schema, mandatory reduced-motion fallback, performance budget, output determinism (entropy tokens like `Math.random`/`Date.now` fail the gate), catalog-SemVer legality, golden creation β and opens a PR. **It cannot merge, publish, or deploy**: structurally (workflow permissions carry no `packages`/`id-token`, PR-only) and by regression test (`forge-workflow-guard` fails CI if anyone smuggles a publish step in). Gate 1 is always a human taste review.
## MCP server
| Tool | Contract |
|---|---|
| `motion_catalog` | primitives + authoring rules + catalog version (16-hex pin) |
| `motion_validate` | fail-closed Trust Boundary; precise `[MS-XXX]` errors; surfaces deprecations |
| `motion_compile` | deterministic spec β code; never emits on a failed validation |
| `motion_audit` | static motion-a11y check of a live URL (read-only, open-world) |
| `motion_stats` | telemetry summary (escalations = catalog growth signal) |
Input is size-capped (`MS-INPUT-TOO-LARGE`, 64 KB). The stdio server exposes one tool factory as the single source of truth, contract-tested in `test/mcp.test.mjs`. A hosted MCP endpoint is live: keyless `motion_catalog` + `motion_validate` at `https://api.motionspec.dev/mcp`; keyed tiers cover compile/audit/stats.
## Motion-a11y checker
`motion audit ` (CLI, `--json` for the machine payload) and the `motion_audit` MCP tool run a **static** scan of a page's HTML and linked stylesheets β no headless browser, no new dependency. It reports four motion problems: CSS animation/transition without a `prefers-reduced-motion` guard (WCAG 2.3.3), animated properties other than transform/opacity, `infinite` animations with no pause path (`animation-play-state`/`data-*`), and `