MotionSpec — web animation accessibility MCP

MotionSpec — Web 动画无障碍 MCP 服务

**MotionSpec 是用于 Web 动画无障碍的 MCP 服务和命令行工具。**它帮助 AI 编码 Agent 和前端开发者将经过验证的动画规范编译为确定性的 GSAP + CSS，并在页面已加载的 CSS 中查找运动无障碍候选项：缺少 prefers-reduced-motion 防护，以及缺少连续动画的暂停路径。

MIT 编译器默认包含减少动态效果处理和循环暂停控制。其静态审计支持审查 **WCAG 2.2.2（暂停、停止、隐藏 — A 级）**和 WCAG 2.3.3（交互产生的动画 — AAA 级）。审计结果需要结合上下文进行审查；扫描结果干净并不代表完成了全面的无障碍或 WCAG 合规评估。运行时 JavaScript 动画、闪烁、视频和 Canvas 不在审计范围内。

• **创建 Web 动画：**选择目录中的基元，验证 JSON 规范，然后编译为原生 GSAP JavaScript 和 CSS。内部的 WAAPI 降级不是公开的构建目标。
• **检查 CSS 动态效果：**审计 URL，查找减少动态效果和暂停路径候选项，然后审查报告中的选择器和建议的修复方案。
• **防止回归：**使用 CI 示例，将审计结果与明确接受的基线进行比较。

本地 stdio MCP 无需 API 密钥即可提供全部五种工具（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 端点已上线：无需密钥即可使用 motion_catalog 和 motion_validate，访问地址为 https://api.motionspec.dev/mcp（streamable-http；编译、审计和统计功能需使用密钥）— 设置指南：https://motionspec.dev/docs。

Claude Code 插件

此仓库也是一个 Claude Code 插件：它打包了 MCP 服务（npx motionspec，包含全部五个工具，本地运行，无需密钥）以及两个技能——/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 审计 · CI 在 Node 18/20/22 上运行，另有 x86 Playwright 端到端测试
目录	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 中存储哈希密钥）· 两阶段速率限制（按 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 规则（位于减少动效防护之外，因此始终生效），以及在 pauseControls: "auto"（故障安全默认值）下生成一个无障碍暂停／停止切换控件（type="button"，aria-pressed 保持同步，目标尺寸 ≥24 px，焦点环可见，减少动效时不渲染）。pauseControls: "api" 保留 CSS 契约，并由集成方提供控件；"off" 可选择退出，但存在持久动效时会发出 MS-GLOBALS-PAUSE-OFF。promote-gate 会拒绝任何未标记为 a11y.persistent 的 infinite／repeat:-1 基元。没有循环的规格不会增加任何额外字节。
5. 确定性 — 相同规格 ⇒ 字节完全一致的代码（GSAP 输出和内部 WAAPI 降级均有黄金文件测试）。
6. 版本化 — 架构已冻结为 v1；目录 SemVer 由差异关卡强制执行（收紧边界却以“patch”版本发布会导致 CI 失败）；规格可以固定 catalogVersion 以确保可复现（MS-CATALOG-PIN-MISMATCH 采取失败关闭策略）。
7. 可观测性 — 每个请求都会记录 model | model-repaired | cache-hit | escalate-*（本地：JSONL 接收器 · 托管：Cloudflare Analytics Engine，并已清除 PII）。升级集群是新增基元的增长信号。

一个构建目标，一个内部降级

如今通过 CLI 或 MCP 工具可以从编译器获取的内容，只有一个目标：

• vanilla-gsap — GSAP + ScrollTrigger。meta.target 不接受其他值（架构已冻结为 v1）。

代码库中还存在第二种降级方式，并由测试套件确保正常运行，但它无法通过任何接口访问：

• WAAPI/CSS 降级（src/compiler/lower-waapi.js）——零 GSAP 输出，基于 Element.animate、IntersectionObserver 和 @keyframes／position: sticky。覆盖完整目录；每个基元的黄金输出字节完全一致；使用相同的无障碍防护和 CSS 安全关卡。这是避免与框架绑定的保障：IR 的生命周期比任何动画库都长。内部功能——仅由测试和 bin/promote-gate.js 引用；没有 CLI 标志、MCP 工具或对应的架构目标（ADR-0001 将 meta.target 冻结为 vanilla-gsap；引擎接线不在范围内，见 ADR-0002）。除非发布说明另有说明，否则不要基于它规划构建。

目录自我扩充——品味由人把关

Catalog Forge（CI 工作流，手动触发）会选取遥测排名最高的缺口，生成一个候选基元，并让它通过多阶段考验——元架构、强制减少动效回退、性能预算、输出确定性（Math.random／Date.now 等熵令牌会导致关卡失败）、目录 SemVer 合规性、黄金文件创建——然后发起 PR。它无法合并、发布或部署：从结构上看（工作流权限不包含 packages／id-token，且仅限 PR），以及通过回归测试保证（如果有人偷偷加入发布步骤，forge-workflow-guard 会导致 CI 失败）。第一道关卡始终是由人进行品味评审。

MCP 服务

工具	契约
motion_catalog	基元 + 编写规则 + 目录版本（16 位十六进制固定值）
motion_validate	故障时拒绝的信任边界；精确的 [MS-XXX] 错误；显示弃用项
motion_compile	确定性地将规范转换为代码；验证失败时绝不生成代码
motion_audit	对实时 URL 进行静态动效辅助功能检查（只读、开放世界）
motion_stats	遥测摘要（升级次数 = 目录增长信号）

输入大小受限（MS-INPUT-TOO-LARGE，64 KB）。stdio 服务将一个工具工厂作为唯一事实来源，并在 test/mcp.test.mjs 中进行契约测试。托管 MCP 端点已上线：无需密钥即可使用 https://api.motionspec.dev/mcp 上的 motion_catalog + motion_validate；编译、审计和统计功能适用于需要密钥的套餐。

动效辅助功能检查器

motion audit <url>（CLI，使用 --json 输出机器可读数据）和 motion_audit MCP 工具会对页面 HTML 及其链接的样式表进行静态扫描——无需无头浏览器，也无需新增依赖。它会报告四类动效问题：CSS 动画/过渡未设置有效的 prefers-reduced-motion 防护（WCAG 2.3.3——防护必须在层叠中胜出）；动画属性不是 transform/opacity；infinite 动画没有暂停途径（animation-play-state/data-*）；以及持续时间超过 5 s 的 <marquee>/自动播放动效（WCAG 2.2.2）。仅颜色/透明度的过渡不属于 2.3.3 所指的动效，因此不会报告；加载指示器（旋转图标、骨架屏）会列为 review 项，不影响评分。每项发现都包含选择器、WCAG 参考和可直接复制粘贴的修复方案。CLI、motion_audit 工具和 motionspec.dev/motion-check 上的免费检查使用相同引擎、限制（12 个样式表、2 MB、8 s）和评分。**它会如实说明自身局限：**运行时动效（WAAPI/GSAP/JS、WebGL 库）会标记为未审计（V2），而不会被默默判定为通过；没有 CSS 动效的页面会显示 status: "not-measurable" 和 score: null，而不是满分。旧版 reduced-motion-safe 徽章字符串仅在页面可测量、没有发现项且没有运行时动效库时返回；它只表示这些检查未在已加载的 CSS 中发现候选问题，并不表示页面或其运行时动效已通过认证。

在 CI 中使用

motion audit --json 足够稳定，可用于把关拉取请求。examples/ci/motion-audit.yml 是一个可复制并按需修改的 GitHub Actions 工作流：它会构建你的网站，在 localhost 上提供构建目录，使用 npx -y -p [email protected] motion audit <url> --json（本地运行、MIT、无需密钥、不会调用托管服务）审计你列出的路径，并将每个页面与已签入的基线 .motionspec/baseline.json 进行比较。

如果页面变得更差，检查就会失败——这与 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（页面不可测量时，score 为 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 兼容；这些检查基于已发布的 test/golden 测试集运行。多个实现通过同一测试集，才能使其成为标准。

标准映射

MotionSpec 检查有限的一组运动信号。这些是供审核的候选项，并非符合性结论，也不能替代对交付界面的测试。

标准	等级	使用 MotionSpec 审查的内容
WCAG 2.2.2 — 暂停、停止、隐藏	A	对于自动开始、持续超过五秒且与其他内容同时显示的非必要移动、闪烁或滚动内容，检查是否提供可用的暂停、停止或隐藏机制。编译器默认提供循环暂停路径；静态审计会查找缺少路径的候选项。自动更新内容另有要求，不受五秒阈值限制。
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 标明某个版本已上线时，该版本才算“上线”，而不是本地运行成功时就算上线。

安全

托管路径采用纵深防御：以恒定时间比较管理员密钥（针对位置和长度均无时序侧信道）· 客户密钥以哈希形式（SHA-256）存储在 KV 中，任何查询错误都会安全失败 · 按 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 和网页搜索渠道，并提供可重复使用的查询日志。
• 使用情况衡量计划 — 当前的本地遥测、拟议的托管汇总计数器，以及 npm 下载统计的局限。
• AGENTS.md — 编码 Agent 应了解的内容：何时使用 MotionSpec、相关命令、三条动态效果规则（减少动态效果 · 暂停路径 · 不闪烁），以及审计不会检查的内容。编辑器中的相同规则：.cursor/rules/motionspec.mdc 和 .github/copilot-instructions.md。
• SECURITY.md — npm 包和托管端点的安全状况。
• docs/adr/0001-schema-freeze-v1.md — 冻结的 v1 契约及其缘由。

贡献

CONTRIBUTING.md 介绍了环境设置、由门禁驱动的 PR 检查清单、提交约定、黄金文件重新生成，以及简短的架构概览。问题模板位于 .github/ISSUE_TEMPLATE/ 下。

许可证

MIT。