Leo-Ayh-Oday / motion-pro-max

Motion Pro Max

Motion is the typography of time.
动效，是时间的排版。

Design-aware motion engineering for coding agents.

Purpose → Engine → Recipe → Implementation → Review → Evidence

---

一页说明

动效是界面里唯一同时具有方向、速度与情感的维度。它最容易让一个产品显得高级，也最容易让它显得廉价——而且，它最容易被大模型写坏。

Motion Pro Max 是一个 Agent Skill Pack，把"是否该动、怎么动、动完怎么审查"组织成一套可执行的工程流程。它教给编码 Agent 的不是 GSAP 语法（那是 GSAP 官方 Skills 的领地），而是动效的设计决策：

这个场景需不需要动效？ 用 CSS、Framer Motion 还是 GSAP？ 多快、多缓、用什么曲线？ 用户关了动画怎么办？ 交付之前，拿什么标准来审？

它怎么工作

一个请求
   │
   ▼
Motion Brief ──────────── 目的先行：吸引注意 / 引导视线 / 反馈 / 过渡 / 氛围
   │
   ▼
引擎路由 ──────────────── CSS Native · Framer Motion · GSAP，不默认任何引擎
   │
   ▼
场景派发 ──────────────── 26 个场景速查：方向 / 插件 / 弹簧 / 时长 / 设计约束
   │
   ▼
实现 ──────────────────── adapter（引擎实现）→ recipe（场景模板）
   │
   ▼
质量门 ────────────────── 🚫 Blocking · ⚠️ Warning · 💭 Preference
   │
   ▼
motion-review ─────────── 独立 Agent 审查，5 维打分，逐项回显
   │
   ▼
Evidence ──────────────── claim → file → line → checker → artifact

每一步只加载当前需要的内容。首屏约 4KB，之后按需深入。

26 场景，一次查表

references/scene-dispatch.md 是唯一权威派发索引。每个场景一行：方向、插件、弹簧、时长、设计约束。

#	场景	弹簧	时长	一句约束
1	Hero 首屏	dramatic	600–900ms	stagger 指数递减 · 禁 ease
3	滚动叙事	cinematic	scrub	单 master timeline · reduced-motion
11	页面过渡	power2.in/out	300–500ms	退场快于入场
15	Modal / Dialog	snappy	200–400ms	遮罩 OKLCH · 退 < 入
16	Toast / 通知	bouncy 入	400/300ms	禁霓虹发光
17	列表增删	snappy	300–500ms	Flip 三步走

完整 26 行 + 7 个弹簧 + 五级运动层级 + 降级矩阵，见 scene-dispatch.md。

质量门：把审美放在该放的位置

质量门只有三档，拒绝把个人偏好包装成安全规则：

🚫 Blocking — 5 项 · 任一不过 = 不能交付
   键盘无障碍 · reduced-motion 降级 · 对比度 · 调试残留 · React cleanup

⚠️ Warning  — 8 项 · 强烈建议修复
   性能风险 · 设计系统一致性 · 节奏与交互完整性

💭 Preference — 9 项 · 按上下文判断
   OKLCH · 阴影分层 · 命名曲线 · 间距习惯 · 品牌字体……

完整清单见 quality-gates.md。

独立审查：不自己给自己打分

生成代码的 Agent 和审查代码的 Agent 不是同一个。motion-review 独立执行 5 维打分（设计系统一致性 / 动效物理感 / 性能 / 可访问性 / 框架正确性），每一项逐条回显证据——禁止只报计数。Blocking > 0 或总分 < 80，不能交付。

与 GSAP 官方 Skills 的关系

GSAP 官方 Skills	Motion Pro Max
GSAP API 正确使用	是否应当使用动效
Timeline / Plugin 语法	产品场景与动效目的
框架集成	CSS / Motion / GSAP 路由
性能实践	设计系统与品牌语言
插件使用	Reduced Motion 语义降级
技术权威	跨引擎质量门与 Evidence

GSAP 官方 Skills 是技术权威；Motion Pro Max 是动效设计决策与交付工作流。GSAP 官方 Skill 可声明为可选技术依赖。

安装

Claude Code

git clone https://github.com/Leo-Ayh-Oday/motion-pro-max
cp -r motion-pro-max/skills/motion-pro-max ~/.claude/skills/
cp -r motion-pro-max/skills/motion-review ~/.claude/skills/

opencode — 在 opencode.json 中：

{
  "skills": {
    "urls": ["https://github.com/Leo-Ayh-Oday/motion-pro-max/tree/main/skills"]
  }
}

Codex — 复制 skills/ 到 Codex 的 skills 目录。

仓库结构

motion-pro-max/
├── skills/
│   ├── motion-pro-max/
│   │   ├── SKILL.md              # 精简入口（~4KB，渐进加载）
│   │   ├── adapters/             # gsap · css-native · motion-react
│   │   ├── recipes/              # 8 个核心场景模板
│   │   ├── references/           # 派发 · 规范 · 质量门 · 配方库
│   │   ├── checks.json           # 机器可执行检查（5/8/9）
│   │   ├── evidence.schema.json
│   │   ├── manifest.json · provenance.json
│   │   └── examples/             # hero-nextjs bad/fixed 对照
│   └── motion-review/            # 独立审查 skill
├── schemas/                      # (v0.2) motion-brief / review-result
├── scripts/                      # (v0.3) checker CLI
├── evals/                        # (v0.4+) benchmark
└── examples/                     # 多框架示例

状态：诚实版

v0.1 — Skill Pack（当前）

• ✅ Agent Skill 路由（26 场景派发）
• ✅ 引擎选择（CSS / Motion / GSAP）
• ✅ Recipe 库（8 核心 + 21 全量）
• ✅ 三级质量门（Blocking / Warning / Preference）
• ✅ 独立 motion-review（5 维打分）
• ✅ Evidence schema + bad/fixed 示例
• ✅ 双语 README · MIT License · Provenance

计划中（不阻塞 v0.1）

• deterministic checker CLI（npx motion-pro-max check ./src）
• Playwright runtime verifier
• 自动修复循环
• Benchmark 套件
• Figma MCP 接入

这是 Skill Pack，不是自动执行的 Harness。能力描述只覆盖已实现的部分——一个诚实的开头，好过一个夸张的版本号。

License

MIT — 本仓库原创内容。GSAP 库本身为 GreenSock 标准许可证（非 MIT）；本仓库不复制或再分发 GSAP 源码，示例仅展示其公共 API 用法。