JuHaoLi/ux-motion-teardown
GitHub: JuHaoLi/ux-motion-teardown
一个 Claude Agent 技能，能将任意网站的动效、滚动触发器和交互设计逆向工程为可复用的参数化规范、设计手册及交互式图表。
Stars: 1 | Forks: 0
# ux-motion-teardown
**给它一个 URL —— 它会将网站的动效 · 滚动 · 交互设计解构为可复用的设计手册 + 交互式图表。**
*这是一个 Claude Agent Skill，能够将任何网站的动效 / 滚动触发器 / UI 设计逆向工程为可复用的规范、设计手册和交互式图表。*
## 这是什么
输入一个链接，它会驱动一个**真实的浏览器**来逐帧观察目标网站——动效轨迹、滚动机制、素材资源、设计 token——并将它们逆向工程为结构化的 `spec.json`（单一事实来源），然后由同一套规范渲染出多种可复用的产出物。
一句话比喻：一个针对 Web 动效的 **“terraform import + 竣工测量员”**——将一个活的、闭源的网站转化为一份干净、可编辑、参数化的蓝图。
**适用场景**：理解动效网站是如何构建的 · 在你构建复刻版之前确定工作范围 · 将网站提炼为 agent 可执行的设计手册。
**不适用场景**：将文章文本抓取为 markdown、发现/对比 GitHub repos、在你已经知道自己想要什么的情况下编写动画代码，或静态 UI 截图 QA——每种场景都有更合适的工具。
## ✨ 三种产出物
| 产出物 | 它是什么 |
|---|---|
| **`spec.json`** | 单一事实来源。一份从运行时逆向工程得出的参数化规范，每个字段都带有置信度标记；下方的两种产出物都是由它渲染而来的。 |
| **设计手册 `.md`** | Agent 可执行：精确的 CSS 变量 / 组件级 CSS / 像素坐标表 / 动效轨迹表 / 代码片段 / 预生成检查清单。 |
| **交互式图表 `.html`** | 拖动播放头以检查每条动效轨迹；替换图片/视频/文本以进行实时预览——可用作你自己网站的原型基础。 |
## 📂 示例交付物
`examples/` 提供了由该技能生成的两个真实交付物（已泛化为可复用模板，无特定品牌数据）——这是感受其输出格式最快的方式：
| 交付物 | 文件 | 备注 |
|---|---|---|
| 🎛 交互式图表 | **[examples/interactive-diagram.html](examples/interactive-diagram.html)** | 拖动播放头；替换图片/视频/文本进行实时预览。**下载并在浏览器中打开**（GitHub 不会渲染 HTML）。 |
| 📖 设计手册 | **[examples/design-manual.md](examples/design-manual.md)** | Agent 可执行：颜色/排版系统 · 素材坐标表 · 滚动时间轴方案 · 可运行的重建骨架。 |
## ⚙️ 环境要求（重要）
- **必需**：claude-in-chrome（真实浏览器 MCP）+ 可访问目标 URL 的网络权限。
- **可选**：若要导出 Word / PDF，请在最后链接现有的文档/导出技能或 `pandoc`（此处未重复造轮子）。
- 在子 agent 可用性方面支持优雅降级：当子 agent 不可用时，自检阶段将被跳过（并会说明情况）——这并非强制阻断。
## 📥 安装
**选项 1 · 插件，一键安装（推荐）**
```
/plugin marketplace add JuHaoLi/ux-motion-teardown
/plugin install ux-motion-teardown
```
**选项 2 · 手动**
```
git clone https://github.com/JuHaoLi/ux-motion-teardown.git
cp -r ux-motion-teardown/skills/ux-motion-teardown ~/.claude/skills/
```
安装完成后，只需在 Claude Code 中提供一个 URL 即可触发它。
## 🚀 用法
提供一个网站 URL + 意图（理解或复刻其动效/滚动/交互设计），例如：
它分为 **5 个阶段**运行（可断点续传，每个阶段生成一个产出物）：
```
0 connect + pass preloader + feed scroll → 1 probe stack + classify → 2 frame-by-frame reverse → 3 land spec → 4 render manual + diagram → 5 adversarial self-check
```
## 🗺 支持的网站类型
`scrollModel.type`（滚动**机制**）× `elementSource`（**内容所在位置**）——这是两个正交的维度，因此需**先分类，再选择模板**：
- **滚动机制**：`none`（静态/单屏） · `native` · `hijack` · `horizontal` · `paged` · `pinned` · `canvas-experience`
- **内容位置**：`dom`（真实 DOM 动画） · `canvas-internal`（WebGL 内部的叙事） · `mixed`（两者交织）
`skills/ux-motion-teardown/assets/` 为三种网站类别提供了**参考规范**（经过实战检验）：
| 组合 | 代表形式 |
|---|---|
| `hijack + dom` | 劫持滚动 + DOM 动画（例如主视觉图线性缩放 2.5×→1×） |
| `hijack + canvas-internal` | 纯 WebGL 叙事，最简 DOM → 截取帧序列 |
| `hijack + mixed` | 3D 主视觉 + 多个交织的动态 DOM 文本部分 |
## 🏗 工作原理：编译器架构
```
Frontend (extract) IR (single source of truth) Backend (render)
┌────────────┐ ┌────────────┐ ┌─▶ design-manual.md
│ frame-by- │ ─clean─▶ │ spec.json │ ─render┼─▶ interactive-diagram.html
│ frame obs. │ │ │ └─▶ rebuild brief → feed another AI
└────────────┘ └────────────┘
```
**铁律**：每个产出物都由同一个规范渲染而成；渲染层绝对不能注入自己的数据（否则事实会产生偏差）。其他红线包括：实测与推断的标记必须严格区分、绝不硬编码无法测量的值、同图缩放 ≠ 两张不同的图片，以及当 canvas 字节流不可用时，应使用坐标 + 占位符，而不是伪造像素。
## 📁 仓库结构
```
ux-motion-teardown/ # repo root = human-facing
├── README.md # this file
├── LICENSE # MIT
├── .claude-plugin/ # plugin manifest (enables /plugin marketplace add)
│ ├── marketplace.json
│ └── plugin.json
├── examples/ # two output samples (interactive diagram + design manual)
└── skills/
└── ux-motion-teardown/ # ← the portable skill itself (this is what gets installed)
├── SKILL.md # entry: 5-stage flow + red lines
├── references/*.md # 7 methodology modules (loaded on demand)
└── assets/ # diagram-template.html + example-*.spec.json
```
## ⚠️ 免责声明
- 本工具仅用于**学习、研究和设计复刻参考**。当你解构自己的目标网站时，输出内容将包含该网站的布局/文案/素材信息，其版权归原网站所有；请在**合理使用**范围内使用，切勿原样照搬受版权保护的素材。
- `examples/` 中的交付物已**泛化为中性模板**（占位文案、匿名化来源、无特定品牌数据）——仅供输出格式演示。
## 📄 许可证
[MIT](LICENSE) © JuHaoLi
MIT © JuHaoLi
标签：Claude Agent Skill, Homebrew安装, UI/UX设计, 动效设计, 后端开发, 多模态安全, 网页逆向分析, 防御加固