MotionSpec
MotionSpec — это open-core слой доверия, который проверяет и компилирует безопасную для reduced-motion анимацию пользовательского интерфейса для веб‑приложений, создаваемых с помощью ИИ. LLM авторизует JSON-спецификацию, валидируемую схемой; детерминированный компилятор порождает чистый GSAP JavaScript + CSS — защищённый от внедрений и валидируемый каталогом по умолчанию, с принудительным fallback под prefers-reduced-motion и бюджетом по производительности, проверяемым в соответствии с WCAG 2.2.2 (Pause, Stop, Hide) и WCAG 2.3.3 (Animation from Interactions).
Запуск двумя способами: как безключевой MCP-сервер, к которому любой host LLM может обратиться (npx motionspec), или как CLI-компилятор в вашем сборочном процессе (motion compile spec.json). В любом случае вы работаете с простыми файлами — сборкой GSAP или беззависимостной WAAPI/CSS-понизацией. Ядро лицензии MIT. Документация: https://motionspec.dev
The thesis: capability lives in the catalog, not the model. Большее модели может писать более подробные спецификации, но она не способна выдать примитив, параметр или селектор, который граница доверия не одобрила. Компилятор доверяет только тому, что прошло проверку.
Routing (small model, Stage A) ──> MotionSpec (JSON) │ cache · 1 repair-retry · escalation │ ▼ ▼ telemetry TRUST BOUNDARY (fail-closed) │ ┌─────────────┴─────────────┐ ▼ ▼ Compiler (no model, Stage B) WAAPI lowering (no GSAP) │ │ out/.motion.js + .css Element.animate / IO / @keyframes">``` 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 (no GSAP) │ │ out/.motion.js + .css Element.animate / IO / @keyframes
Not to be confused with
> Not to be confused with: класс MotionSpec из Android Material Components, MotionSpec у iOS material-motion, Motion.dev / Framer Motion, приложение календаря usemotion.com, бренд Mobility Motion Specialties, или генераторы текста в видео (Runway/Sora/Kling/Viggle). MotionSpec проверяет именно анимацию пользовательского интерфейса внутри веб‑приложений — он не генерирует видео.
## 60-second start
npx motionspec # stdio MCP server — install not required claude mcp add motionspec -- npx motionspec # зарегистрировать в Claude Code / любой MCP host
npm install -g motionspec # или используйте CLI: motion compile spec.json # детерминированная сборка → ./out в вашем cwd
Хостовая LLM‑модель формирует спецификацию; граница доверия остаётся принудительной независимо от способа. Зарегистрирован в MCP Registry как `io.github.MasterPlayspots/motionspec`. Готовый MCP-эндпойнт в работе: безключевые маршруты `motion_catalog` + `motion_validate` по адресу `https://api.motionspec.dev/mcp` (streamable-http; уровни доступа по ключам охватывают сборку/аудит/статистику) — настройка: [https://motionspec.dev/docs](https://motionspec.dev/docs).
### Claude Code plugin
Этот репозиторий также является плагином Claude Code: он объединяет MCP-сервер (`npx motionspec`, все пять инструментов, локально, без ключа) с двумя навыками — `/motionspec:motion` (автор→валидaция→компиляция) и `/motionspec:audit <url>` (проверка доступности движения, WCAG 2.2.2/2.3.3). Попробуйте напрямую из клона с `claude --plugin-dir .`, или установите его через Marketplace после регистрации:
/plugin marketplace add anthropics/claude-plugins-community /plugin install motionspec@claude-community
## Status
| | |
| --- | --- |
| Version | v1.2.6 · схема зафиксирована на spec v1 (ADR-0001, подписан) |
| Published | npm motionspec (82 kB упаковано, 67 файлов, ничего только для продакшн) · MCP Registry |
| Tests | 295 зелёных тестов — защита от инъекций, fuzz на 6000 спецификаций, детерминизм по умолчанию, паритет схем, pause‑control, аудит доступности motion · CI на Node 18/20/22 + x86 Playwright e2e |
| Catalog | 40 примитивов, все верифицированы на устройстве, обязательный fallback на reduced-motion; 18 непрерывных циклов также содержат путь паузы WCAG-2.2.2 |
| Supply chain | 2 зависимости во время выполнения (MCP SDK, zod — обе зафиксированы) · 0 уязвимостей · CycloneDX SBOM зафиксирован · все лицензии разрешительные · CI actions SHA‑fixed |
| Coverage | ≈99% строк / ≈98% функций / ≈80% ветвлений кода src/ + worker/ (CI порог: 90/90/75) |
| Last audit | 2026-07-03 — 17/17 согласований интеграции подтверждены, инфра 8.1/10, безопасность: 0 критических, полный гита‑история секреты не найдены |
| First client | CHS Computer — живёт на Vercel |
| Hosted MCP | живой — безключевые motion_catalog/motion_validate по адресу api.motionspec.dev/mcp · keyed tier: Cloudflare Worker, по ключу ограниченный доступ (хэш‑ключи в KV) · двухступенчатый rate limiting (до-авторизация по IP + по ключу) · canary/minute + внешний heartbeat (случ. сбой → оповещение за 5 s) | 2.2.2 / 2.3.3 | clause 9 (web) | WCAG‑инкорпорированные критерии успеха | предпродажная самопроверка для покрытых продуктов |
Примечания: EN 301 549 — европейский гармонизированный стандарт, ч. 9 которого применяет критерии WCAG по номеру. США Section 508 (изменённая версия) включает WCAG 2.0 Уровни A и AA — SC 2.2.2 относится к уровню A и входит в сферу охвата; SC 2.3.3 — AAA и предоставляется как более строгая гарантия по сравнению с базовым требованием. Европейский акт доступности (EAA) и его немецкая транспозиция (BFSG, применимо с 28 июня 2025) требует доступности цифровых продуктов и услуг, с сопоставлением обычно по EN 301 549. MotionSpec обеспечиваетsubset движения этих требований по конструированию; он сам по себе не делает продукт полностью соответствующим.
## Quickstart (from a clone)
npm ci # установка (0 зависимостей во время выполнения помимо MCP SDK + zod) npm test # 295 тестов: валидатор, золотые копии, маршрутизатор, fuzz, паритет node bin/motion.js catalog # примитивы + версия каталога node bin/motion.js compile examples/hero.motionspec.json node bin/motion.js pipeline "Hero headline fades in, cards staggered" --mock node bin/motion.js stats # телеметрия (модель / исправлено / cache-hit / escalation)
Живую модель вместо `--mock`: задайте `MOTION_API_KEY` (или `OPENROUTER_API_KEY`); необязательная `MOTION_MODEL` (по умолчанию `anthropic/claude-haiku-4.5`) и `MOTION_BASE_URL` (любой совместимый с OpenAI endpoint). См. файл `.env.example`.
### Gates (run these — they are the contract)
npm test # полный пакет тестов, защита границы доверия + детерминизм золотых копий npm run coverage # НЕ ПРОХОДИТ при 90/90/75 (линии/функции/ветви) npm run catalog-lock:check # ADR-0001 D2: ужатое ограничение, выпущенное как "патч", здесь провалится npm run sbom && npm run sbom:check && node bin/license-check.js npm run e2e # реальный браузерный Playwright (CI x86 runner)
Релизы проходят всю цепочку и завершаются для канонического клон‑guard и проверкой доверия к реестру — версия считается "живой", когда npm dist-tag говорит об этом, а не когда локальный прогон прошёл успешно.
## Security
Защита в глубину на hosted‑пути: сопоставление admin-secret в постоянном времени (без утечки по позиции или длине) · ключи клиентов хранятся атакументированными как хэш (SHA-256) в KV, отказ от доступа при любой ошибке поиска · ограничение запросов до авторизации по IP и далее по ключу, сигнальные оповещения об злоупотреблениях без PII · телеметрия очищается перед сохранением · строгие CSP/`X-Frame-Options`/`nosniff` на единственной странице без гейта (панель данных без данных). Полная поза‑тура и отчётность: SECURITY.md. Последний аудит (2026-07-03): критических находок нет, секреты никогда не коммитились в 197 коммитах истории.
## Layout
schema/ MotionSpec JSON схема (статический контракт, паритет-тестируется с валидатором)
primitives/ каталог: 40 проверенных примитивов (безопасные шаблоны)
catalog.lock.json выпущенная база каталога (Разница SemVer)
src/compiler/ validate.js (Trust Boundary) · compile.js (GSAP) · lower-waapi.js (WAAPI/CSS)
safety.js (одна общая CSS-ворота) · keyword-map.js · catalog.js · catalog-semver.js
src/router/ prompt.js · clients.js (openai-compat + mock) · route.js · cache.js · telemetry
src/mcp/ server.mjs (stdio) · register-tools.js (shared tool factory)
src/forge/ generate.js · prioritize.js — проверенный рандоматор каталог-кузнечик
src/discover/ gap analysis: request intents ↔ catalog coverage
src/demo/ device-verification demo pages (?rm=1 simulates reduced motion)
bin/ motion.js (CLI) · promote-gate.js — dev/CI gate scripts stay repo-only
test/ 295 tests incl. injection, fuzz, goldens (both targets), parity; test/e2e (Playwright)
docs/ ADR records (docs/adr/) and per-primitive reference (docs/primitives/)
## Docs
- [SECURITY.md](https://github.com/MasterPlayspots/motionspec/blob/main/SECURITY.md) — security posture of the npm package and hosted endpoint.
- `docs/adr/0001-schema-freeze-v1.md` — зафиксированный контракт v1 и почему.
## Contributing
[CONTRIBUTING.md](https://github.com/MasterPlayspots/motionspec/blob/main/CONTRIBUTING.md) охватывает настройку, gate‑управляемый чек-лист PR, соглашения по коммитам, регенерацию золотых файлов и краткий обзор архитектуры. Шаблоны задач размещены в `.github/ISSUE_TEMPLATE/`.
## License
MIT.