MotionSpec — web animation accessibility MCP

MotionSpec — web animation accessibility MCP server

MotionSpec is an MCP server and CLI for web animation accessibility. It helps AI coding agents and frontend developers compile validated animation specs to deterministic GSAP + CSS and find motion-accessibility candidates in a page's loaded CSS: missing prefers-reduced-motion guards and missing pause paths for continuous animation.

The MIT compiler includes reduced-motion handling and loop pause controls by default. Its static audit supports review of WCAG 2.2.2 (Pause, Stop, Hide — Level A) and WCAG 2.3.3 (Animation from Interactions — Level AAA). Findings need contextual review; a clean scan is not a full accessibility or WCAG-conformance assessment. Runtime JavaScript animation, flashing, video and Canvas are outside the audit's scope.

• Create web animation: choose a catalog primitive, validate a JSON spec, then compile vanilla-GSAP JavaScript and CSS. The internal WAAPI lowering is not a public build target.
• Check CSS motion: audit a URL for reduced-motion and pause-path candidates, then review the reported selectors and suggested fixes.
• Prevent regressions: use the CI example to compare findings against an explicitly accepted baseline.

Local stdio MCP exposes all five tools without an API key (npx -y motionspec). The hosted endpoint at https://api.motionspec.dev/mcp provides keyless motion_catalog, motion_validate, motion_compile and motion_audit; only motion_stats (the operator's telemetry of the hosted service) requires the operator key. See the installation guide and motion accessibility guide. Docs and product: https://motionspec.dev/docs.

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

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, motion_compile and motion_audit at https://api.motionspec.dev/mcp (streamable-http; motion_stats is operator-only) — setup: https://motionspec.dev/docs.

In ChatGPT: MotionSpec is listed in the ChatGPT plugin directory. It offers motion_catalog and motion_validate, no login. It does not compile or check websites; for that, use the hosted endpoint above or the local server. No MotionSpec tool certifies accessibility. Listing: https://chatgpt.com/plugins/plugin_asdk_app_6ad7946fedac819183fb38ac85520e4b

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:

/plugin marketplace add anthropics/claude-plugins-community

/plugin install motionspec@claude-community

Status

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

| `mot