MotionSpec — web animation accessibility MCP

MotionSpec — Web アニメーションのアクセシビリティ向け MCP サーバー

MotionSpec は、Web アニメーションのアクセシビリティ向け MCP サーバーおよび CLI です。 AI コーディングエージェントやフロントエンド開発者が、検証済みのアニメーション仕様を決定論的な GSAP + CSS にコンパイルし、ページに読み込まれた CSS 内からモーションアクセシビリティ上の候補を見つけられるようにします。対象となる候補は、prefers-reduced-motion ガードの欠如や、連続アニメーションを一時停止する手段の欠如です。

MIT ライセンスのコンパイラーには、デフォルトで視差効果の軽減への対応とループの一時停止コントロールが含まれています。静的監査は、WCAG 2.2.2（Pause, Stop, Hide — レベル A） および WCAG 2.3.3（Animation from Interactions — レベル AAA） のレビューをサポートします。検出結果にはコンテキストに応じたレビューが必要です。問題が検出されなくても、アクセシビリティや WCAG 適合性の完全な評価にはなりません。実行時の JavaScript アニメーション、点滅、動画、Canvas は監査の対象外です。

• Web アニメーションを作成する： カタログのプリミティブを選び、JSON 仕様を検証してから、vanilla-GSAP の JavaScript と CSS にコンパイルします。内部の WAAPI への変換は、公開ビルドターゲットではありません。
• CSS のモーションを確認する： URL を監査して、視差効果の軽減や一時停止手段に関する候補を見つけ、報告されたセレクターと修正案をレビューします。
• リグレッションを防ぐ： CI の例を使って、検出結果を明示的に承認したベースラインと比較します。

ローカルの stdio MCP では、API キーなしですべての 5 つのツールを利用できます（npx -y motionspec）。ホスト型エンドポイント https://api.motionspec.dev/mcp では、キーなしで motion_catalog と motion_validate を利用できます。ホスト型のコンパイル、監査、統計情報にはキーが必要です。インストールガイドとモーションアクセシビリティガイドを参照してください。ドキュメントと製品：https://motionspec.dev/docs。

基本方針：能力はモデルではなくカタログにあります。 より大きなモデルなら、より複雑な仕様を作成できます。しかし、Trust Boundary が承認していないプリミティブ、パラメーター、セレクターを出力することはできません。コンパイラーが信頼するのは、検証を通過したものだけです。

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

混同しないでください

混同しないでください： Android Material Components の MotionSpec クラス、iOS の material-motion MotionSpec、Motion.dev / Framer Motion、usemotion.com のカレンダーアプリ、Motion Specialties のモビリティブランド、またはテキストから動画を生成するサービス（Runway/Sora/Kling/Viggle）とは別のものです。MotionSpec が確認するのは、Web アプリ内の UI アニメーションであり、動画は生成しません。

60 秒で始める

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

ホスト側の LLM が仕様を作成します。どちらの場合も Trust Boundary の適用は維持されます。MCP Registry には io.github.MasterPlayspots/motionspec として登録されています。ホスト型 MCP エンドポイントが稼働中です。https://api.motionspec.dev/mcp で、キーなしの motion_catalog と motion_validate を利用できます（streamable-http。キーが必要なプランではコンパイル／監査／統計情報を利用できます）。セットアップ：https://motionspec.dev/docs。

Claude Code プラグイン

このリポジトリは Claude Code プラグインでもあります。MCP サーバー（npx motionspec、5 つすべてのツール、ローカル、キー不要）と、2 つのスキル — /motionspec:motion（作成→検証→コンパイルのワークフロー）および /motionspec:audit <url>（モーションのアクセシビリティチェック、WCAG 2.2.2/2.3.3）を同梱しています。クローンから claude --plugin-dir . を実行してすぐに試すことも、掲載後にコミュニティマーケットプレイスからインストールすることもできます。

/plugin marketplace add anthropics/claude-plugins-community
/plugin install motionspec@claude-community

ステータス

バージョン	v1.2.10 · スキーマは spec v1 で凍結済み（ADR-0001、署名済み）
公開先	npm motionspec（パッケージ化時 105 kB、67 ファイル、開発専用のものは一切含まれません） · MCP Registry
テスト	374 件すべて成功 — インジェクション攻撃、6000 件の spec ファジング、ゴールデンテストによる決定性、スキーマの同等性、一時停止コントロール、motion-a11y 監査 · Node 18/20/22 + x86 Playwright e2e で CI を実行
カタログ	40 個のプリミティブ、すべてデバイスで検証済み、reduced-motion フォールバック必須。継続ループ 18 個には WCAG-2.2.2 の一時停止手段も用意
サプライチェーン	ランタイム依存関係 2 件（MCP SDK、zod — どちらもバージョン固定） · 脆弱性 0 件 · CycloneDX SBOM を再生成し CI でチェックイン · すべて許容的ライセンス · CI アクションは SHA で固定
カバレッジ	src/ の行カバレッジ 97.23% / 関数カバレッジ 95.17% / 分岐カバレッジ 80.82%（npm run coverage、2026-10-08；CI ゲート 90/90/75）
最終監査	2026-07-03 — 統合ハンドシェイク 17/17 件を証跡で確認、インフラ 8.1/10、セキュリティ：重大な問題 0 件、Git の全履歴を対象としたシークレットスキャンで問題なし
最初のクライアント	CHS Computer — Vercel で稼働中
ホスト型 MCP	稼働中 — キー不要の motion_catalog/motion_validate を api.motionspec.dev/mcp で提供 · キー認証ティア：Cloudflare Worker、キーごとのアクセス制御（ハッシュ化したキーを KV に保存） · 2 段階レート制限（認証前は IP ごと、認証後はキーごとに制限、バーストを検証済み） · 分ごとの cron カナリア + 外部ハートビート（合成障害 → 5 分未満でアラート、実際のインフラで実証済み） · Analytics Engine による運用テレメトリー（リクエスト本文、spec、エラーテキストは保存されません） · アクセス制限付き /dashboard

スキーマ v1 は凍結済みです。specVersion "1.0" は安定した公開契約であり、"0.1" は非推奨ですが v1.2 まで受け付けます（見直しを強制するトリップワイヤーテストを実施）。[MS-XXX] エラーコードレジストリは公開 API であり、コードを再利用したり再定義したりすることはありません。

コンパイラーが保証すること

1. 許可リスト — カタログにないプリミティブがコンパイラーに到達することはありません。
2. インジェクション耐性 — ID、セレクター、文字列パラメーター、トリガーは文字セット検証されます。すべての埋め込みは、JS リテラル（JSON.stringify）か、単一の共有安全性ゲート（safety.js）を通した CSS 検査済みの生値です。悪意のあるモデル出力はフェイルクローズで拒否されます。6000 件を超えるランダムな仕様でテストおよびファジング済みです。
3. 構築段階で確保されるアクセシビリティ（モーション） — 安全なデフォルト、強制されるゲート、ビルドごとの証明を備えています。respectReducedMotion はコンパイラーレベルでデフォルト有効（フェイルセーフ）です。省略しても prefers-reduced-motion ガードが適用されます。無効化も可能ですが、MS-GLOBALS-RRM-OFF が出力されます。プロンプト側の指示だけでガードを無効にすることはできません。
4. ループの一時停止／停止（WCAG 2.2.2） — すべての連続ループプリミティブに a11y.persistent のタグが付けられ、コンパイラーは構築段階で一時停止経路を出力します。html[data-ms-paused] をキーとする animation-play-state: paused ルール（reduced-motion ガードの外側にあるため、常に有効）に加え、pauseControls: "auto"（フェイルセーフのデフォルト）の場合は、アクセシブルな一時停止／停止トグル（type="button"、同期された aria-pressed、24 px 以上のターゲット、表示されるフォーカスリング、reduced motion 時にはレンダリングされないもの）を1つ出力します。pauseControls: "api" は CSS の仕様を維持し、コントロールをインテグレーターに委ねます。"off" で無効にできますが、継続するモーションがある場合は MS-GLOBALS-PAUSE-OFF が出力されます。promote-gate は、a11y.persistent でない infinite／repeat:-1 プリミティブを拒否します。ループのない仕様では、追加バイト数はゼロです。
5. 決定性 — 同じ仕様 ⇒ バイト単位で同一のコード（GSAP 出力および内部の WAAPI 変換のゴールデンファイルテストを実施）。
6. バージョン管理 — スキーマは v1 で凍結されています。カタログの SemVer は差分ゲートで適用されます（上限を厳しくした変更を「パッチ」としてリリースすると CI が失敗します）。再現性のため、仕様で catalogVersion を固定できます（MS-CATALOG-PIN-MISMATCH はフェイルクローズ）。
7. 可観測性 — リクエストごとに model | model-repaired | cache-hit | escalate-* を記録します（ローカル：JSONL シンク · ホスト環境：PII を除去した Cloudflare Analytics Engine）。エスカレーションのクラスターは、新しいプリミティブを追加するための成長シグナルです。

1つのビルドターゲット、1つの内部変換

現在、CLI または MCP ツールからコンパイラーを通じて利用できるターゲットは、次の1つだけです。

• vanilla-gsap — GSAP + ScrollTrigger。meta.target はこれ以外を受け付けません（スキーマは v1 で凍結されています）。

コードベースにはもう1つの変換処理があります。テストスイートで成功する状態に維持されていますが、どのインターフェースからも利用できません。

• WAAPI/CSS 変換（src/compiler/lower-waapi.js） — Element.animate、IntersectionObserver、@keyframes／position: sticky を使った、GSAP を一切含まない出力です。カタログ全体を網羅し、プリミティブごとにバイト単位で同一のゴールデン出力を生成します。同じアクセシビリティガードと、同じ CSS 安全性ゲートを備えています。これはフレームワークからの独立性を確保するための備えです。IR はあらゆるアニメーションライブラリより長く存続します。内部専用 — 参照しているのはテストと bin/promote-gate.js のみです。CLI フラグも、MCP ツールも、スキーマターゲットもありません（ADR-0001 で meta.target は vanilla-gsap に固定されています。エンジンの接続は対象外です。ADR-0002）。リリースノートに変更が記載されるまでは、これを前提にビルドを計画しないでください。

カタログは自ら成長し、人間がセンスを保つ

Catalog Forge（CI ワークフロー、手動ディスパッチ）は、テレメトリーのランキングで最上位の不足項目を選び、候補となるプリミティブを1つ生成して、複数段階の審査プロセスにかけます。審査には、メタスキーマ、必須の reduced-motion フォールバック、パフォーマンス予算、出力の決定性（Math.random／Date.now のようなエントロピートークンはゲートで失敗）、カタログの SemVer 準拠、ゴールデンファイルの作成が含まれます。その後、PR を作成します。マージ、公開、デプロイはできません。これは構造的な制約（ワークフローの権限に packages／id-token がなく、PR の作成のみ）と回帰テスト（誰かが公開ステップを紛れ込ませると forge-workflow-guard が CI を失敗させる）によって保証されています。ゲート1は常に、人間がセンスを確認します。

MCP サーバー

ツール	契約
motion_catalog	プリミティブ＋作成ルール＋カタログのバージョン（16 桁の 16 進数ピン）
motion_validate	フェイルクローズの Trust Boundary；正確な [MS-XXX] エラー；非推奨項目を表示
motion_compile	決定論的な仕様 → コード；検証に失敗した場合は出力しません
motion_audit	公開 URL の静的なモーションアクセシビリティチェック（読み取り専用、オープンワールド）
motion_stats	テレメトリーの概要（エスカレーション＝カタログの拡大を示すシグナル）

入力サイズには上限があります（MS-INPUT-TOO-LARGE、64 KB）。stdio サーバーは、単一のツールファクトリーを唯一の信頼できる情報源として公開し、test/mcp.test.mjs で契約テストを実施しています。ホスト型 MCP エンドポイントが稼働中です。キー不要の motion_catalog と motion_validate は https://api.motionspec.dev/mcp で利用でき、キー付きのプランでは compile／audit／stats を利用できます。

Motion-a11y チェッカー

motion audit <url>（CLI、機械可読ペイロードには --json）と motion_audit MCP ツールは、ページの HTML とリンクされたスタイルシートを静的にスキャンします。ヘッドレスブラウザーも、新たな依存関係も不要です。次の 4 種類のモーションに関する問題を報告します。効果的な prefers-reduced-motion ガードがない CSS アニメーション／トランジション（WCAG 2.3.3 — カスケードでガードが優先される必要があります）、transform／opacity 以外のアニメーション対象プロパティ、一時停止方法（animation-play-state／data-*）のない infinite アニメーション、および 5 秒を超える <marquee>／自動再生モーション（WCAG 2.2.2）。色／不透明度のみのトランジションは 2.3.3 におけるモーションではないため、報告されません。ローディングインジケーター（スピナー、スケルトン）は、スコアに影響しない review 項目として一覧表示されます。CLI、motion_audit ツール、motionspec.dev/motion-check の無料チェックは、同じ制限（スタイルシート 12 個、2 MB、8 秒）と同じスコアで、同一のエンジンを実行します。制限について正直に示します。 ランタイムのモーション（WAAPI／GSAP／JS、WebGL ライブラリ）は、黙って合格とするのではなく、未監査（V2） として報告されます。また、CSS モーションがないページは満点ではなく、score: null の status: "not-measurable" になります。従来の reduced-motion-safe バッジ文字列が返されるのは、測定可能なページで検出項目がゼロ、かつランタイムのモーションライブラリがない場合のみです。これは、読み込まれた CSS にこれらのチェックで候補が見つからなかったことだけを意味し、ページやそのランタイムのモーションが認定されていることを意味するものではありません。

CI での使用

motion audit --json は、プルリクエストのゲートとして使用できるほど安定しています。examples/ci/motion-audit.yml は、サイトをビルドし、localhost でビルドディレクトリを配信し、npx -y -p [email protected] motion audit <url> --json（ローカル、MIT、キー不要、ホスト型サービスへの接続なし）を使って指定したパスを監査し、各ページをチェックイン済みのベースライン .motionspec/baseline.json と比較する、コピーして調整できる GitHub Actions ワークフローです。

ページが悪化した場合にゲートが失敗します。これは、MotionSpec の週次再スキャンで使われるものと同じルールです。スコアが低下した場合、または Level-A 検出項目（WCAG 2.2.2 一時停止、停止、非表示）の数が増加した場合に該当します。スコアを比較するのは、両方の実行が測定可能で、同じスコアリングバージョンを使っている場合のみです。1.2.7 以前（スコアリング v1）で作成されたベースラインは、一度再ベースライン化する必要があります。ベースラインにないページは失敗しません。その実行がベースラインになります。再ベースライン化は、意図的な手動実行（workflow_dispatch で update_baseline: true）で行い、新しいファイルをコミット用のアーティファクトとしてアップロードします。ワークフローが独自にコミットすることはありません。修正済みの検出項目は - fixed: 行、新規の検出項目は + new finding: 行として一覧表示されます。

機械可読ペイロードは { ok, url, status, score, scoring, scoring_doc, summary, badge, findings, groups, disclosures, coverage } です。score を使う前に status を確認してください（ページが測定可能でない場合は null です）。audit が対象にするのはディレクトリではなくURLであるため、ローカルサーバーの手順が必要です。また、対象範囲に関する注意事項も併せて示されます。これは静的な CSS スキャンです（インラインの style=""、@import、CSS-in-JS、外部 JS バンドル、動画／GIF／Canvas、点滅チェックは対象外です）。ゲートが緑であることは「読み込まれた CSS に回帰がない」ことを意味し、「アクセシブル」であることを意味するわけではありません。

仕様と適合性

MotionSpecは、単なるツールではなく、管理されたフォーマットです。規範仕様はSPEC.md（バージョン1.0。JSON Schemaに対するRFC-2119のMUST／SHOULD／MAYと、文書化されたADRベースの変更プロセス）です。CONFORMANCE.mdでは、実装がMotionSpec 1.0 compatibleを名乗るために合格すべき5つのチェック（スキーマ、診断、出力、決定性、アクセシビリティ）を定義しており、公開されているtest/goldenコーパスを使って実行します。複数の実装が同じコーパスに合格することで、標準として確立されます。

標準との対応

MotionSpecがチェックするのは、限られたモーションシグナルです。これらはレビューの候補であり、適合性の判定でも、提供されるインターフェースのテストの代わりでもありません。

基準	レベル	MotionSpecで確認する内容
WCAG 2.2.2 — 一時停止、停止、非表示	A	重要でない動くコンテンツ、点滅するコンテンツ、スクロールするコンテンツが自動的に開始し、5秒を超えて続き、ほかのコンテンツと並んで表示される場合、使いやすい一時停止、停止、または非表示の仕組みがあるか確認します。コンパイラはデフォルトでループの一時停止パスを提供します。静的監査では、パスがない可能性のある箇所を探します。自動更新されるコンテンツには、5秒のしきい値を適用しない別の要件があります。
WCAG 2.3.3 — インタラクションによるアニメーション	AAA	インタラクションによってトリガーされる重要でないモーションは、無効化できなければなりません。動きを抑える設定への対応は、その実装方法の一つです。メディアクエリーがないことだけでは不適合とは判断できず、見つかったからといって適合しているとも判断できません。

transformとopacityだけをアニメーションさせることは、パフォーマンス上の推奨事項であり、それ自体はWCAGの成功基準ではありません。この監査では、点滅（2.3.1）、実行時のGSAP／WAAPI、動画、Canvas、一時停止コントロールの使いやすさは測定しません。EN 301 549、Section 508、EAA、BFSG、その他の法的枠組みへの準拠を証明するものでもありません。

クイックスタート（クローンから）

npm ci                                      # install (0 runtime deps beyond MCP SDK + zod)
npm test                                    # 374 tests: validator, goldens, router, fuzz, parity
node bin/motion.js catalog                  # primitives + catalog version
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                    # telemetry (model / repaired / cache-hit / escalate)

--mockではなくライブモデルを使う場合は、MOTION_API_KEY（またはOPENROUTER_API_KEY）を設定します。MOTION_MODEL（デフォルトはanthropic/claude-haiku-4.5）とMOTION_BASE_URL（OpenAI互換エンドポイントならどれでも）は任意です。.env.exampleを参照してください。

ゲート（実行してください — これが契約です）

npm test                   # full suite, fail-closed trust boundary + golden determinism
npm run coverage           # FAILS under 90/90/75 (lines/functions/branches)
npm run catalog-lock:check # ADR-0001 D2: a tightened bound shipped as a "patch" fails here
npm run sbom && npm run sbom:check && node bin/license-check.js
npm run e2e                # real-browser Playwright (CI x86 runner)

リリースでは、正規クローンのガードを含む一連の処理をすべて実行し、最後にレジストリの実態確認を行います。バージョンが「公開中」とみなされるのは、ローカル実行が成功したときではなく、npmのdist-tagがそう示しているときです。

セキュリティ

ホストされる経路では、多層防御を採用しています。管理者シークレットの比較は定時間で行い、位置にも長さにもタイミングサイドチャネルが発生しません。顧客キーはKVにハッシュ化（SHA-256）して保存し、照会エラーが発生した場合はすべてフェイルクローズします。認証処理の開始前にはIPごとの事前認証レート制限を適用してキー列挙の隙間をふさぎ、認証後はキーごとのレート制限を適用します。悪用アラートはPIIを一切含まず、スロットリングされます。テレメトリーは保存前にスクラブされます。認証ゲートのない唯一のページ（データを含まないダッシュボードのシェル）には、厳格なCSP／X-Frame-Options／nosniffを設定しています。報告を含むセキュリティ体制の全容はSECURITY.mdを参照してください。直近の監査（2026-07-03）では重大な指摘はなく、197件のコミット履歴を通じてシークレットがコミットされたことは一度もありません。

レイアウト

schema/            MotionSpec JSON schema (static contract, parity-tested against the validator)
primitives/        catalog: 40 verified primitives (safe templates)
catalog.lock.json  released catalog baseline (SemVer diff-gate)
src/compiler/      validate.js (Trust Boundary) · compile.js (GSAP) · lower-waapi.js (WAAPI/CSS)
                   safety.js (one shared CSS gate) · 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 — the gauntlet-verified catalog forge
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/              374 tests incl. injection, fuzz, goldens (GSAP + internal WAAPI lowering), parity; test/e2e (Playwright)
docs/              ADR records (docs/adr/) and per-primitive reference (docs/primitives/)

ドキュメント

• Web アニメーションのアクセシビリティ — 動きを減らす設定、一時停止コントロール、GSAP の出力、レビューのワークフロー、監査の制限事項。
• ディスカバリーと検索の測定 — レジストリ、GitHub、npm、Web 検索の各サーフェスを分け、再現可能なクエリログを記録します。
• 使用状況の測定計画 — 現在のローカルテレメトリ、提案中のホスト型集計カウンター、npm のダウンロード統計の制限事項。
• AGENTS.md — コーディングエージェントが知っておくべきこと：MotionSpec を使うタイミング、コマンド、3 つのモーションルール（動きを減らす設定・一時停止の手段・点滅なし）、および監査でチェックしない項目。エディター向けに同じルールを記載したファイル：.cursor/rules/motionspec.mdc および .github/copilot-instructions.md。
• SECURITY.md — npm パッケージとホスト型エンドポイントのセキュリティ体制。
• docs/adr/0001-schema-freeze-v1.md — 凍結された v1 の契約と、その理由。

コントリビューション

CONTRIBUTING.md では、セットアップ、ゲート主導の PR チェックリスト、コミット規約、ゴールデンファイルの再生成、簡潔なアーキテクチャの概要について説明しています。Issue テンプレートは .github/ISSUE_TEMPLATE/ にあります。

ライセンス

MIT。