UI 克隆:测量参考,重建它,证明它匹配
每项工作都遵循一个循环:捕获参考 → 测量它(尽可能读取精确值,否则测量像素)→ 编写规范 → 在用户的栈中构建 → 以相同方式捕获我们构建的结果 → 比较 → 修复,直到规范通过。交付物是用户项目中的代码加上证据(数字、差异图像、并排对比表),绝不是“看起来差不多”。方法改编自 NiazMorshed2007/reanimate 和 rossark0/rossark-motion-skill(均为 MIT 协议);这里的每个脚本都是我们自己的。
<skill> = 此技能所在的文件夹。工作放在项目中的 ./ui-clone/<name>/ 下:ref/、ours/、figma/、compare-N/、diff-N/、spec.md。除非用户希望将证据提交到版本控制,否则将 ui-clone/ 添加到 .gitignore。
设置(每台机器一次)
- Python(numpy + Pillow):
~/.ui-clone/venv/bin/python(如果不存在,请使用python3 -m venv ~/.ui-clone/venv && ~/.ui-clone/venv/bin/pip install numpy pillow创建)。使用-I运行脚本。 - 浏览器捕获(Playwright + Chromium,约 250 MB,仅用于 URL / 开发服务器输入):运行器位于
~/.ui-clone/runner(在那里执行npm i [email protected] && npx [email protected] install chromium)。使用node <skill>/scripts/<script>.mjs运行.mjs脚本(它们从~/.ui-clone/runner加载 Playwright,或UICLONE_RUNNER;如果 Playwright 自己的 Chromium 未安装,它们会使用 Playwright 缓存中的任何 Chromium,或UICLONE_CHROMIUM)。 - ffmpeg/ffprobe 在 PATH 上。仅 Figma:在环境中、项目的
keys.env或~/.ui-clone/keys.env中设置FIGMA_TOKEN=...(只读个人访问令牌)。切勿打印或提交令牌。 在安装任何缺失的内容之前,请先询问。
0. 范围(spec.md 顶部,在任何捕获之前)
- 目标: 精确说明要克隆什么(URL + 选择器、文件 + 时间范围 + 裁剪、Figma 节点),不再多。
- 保真度(在第一次回复中说明;它决定验证什么):
级别 何时使用 必须匹配 可以不同 运动忠实(对其他人的作品默认) “让我们的作品感觉/运动起来像他们的” 结构和比例、顺序、时间±0.08秒、缓动族、过冲、相对于大小的位移、交错 文案、颜色、字体、图片、品牌 像素忠实 用户自己的设计(Figma → 代码)、自己的网站、他们有权限的客户工作,或私人练习 以上所有内容 + 字体、大小、间距、颜色、圆角、阴影、资源;截图差异 ≤ 2%(静止状态≤ 0.5%),无测量的偏移 他们没有要求更改的任何内容 混合 “克隆 X 并添加 Y” 克隆部分采用上述其中一个级别 添加的部分(单独保留、展示、检查是否不破坏克隆) - 权利: 其他公司 UI、Logo、插画、字体和文案的像素忠实副本属于他们;仅用于学习目的或获得许可,切勿将其作为用户自己的作品发布。当参考是第三方产品且用户想要发布时,默认采用运动忠实级别并使用他们自己的设计,并说明原因。
- 目标位置: 代码将放在哪里以及使用哪个栈。读取
package.json、现有组件、样式系统(Tailwind 配置、CSS 变量、设计令牌)和已使用的动画库;匹配它们,而不是添加新库。
1. 选择输入方法(最精确的可用方法;说明你使用哪一个)
| 输入 | 捕获 | 你得到什么 |
|---|---|---|
| 实时 URL | inspect_web.mjs + capture_web.mjs | 精确的 CSS 值、字体、声明的持续时间/延迟/缓动、关键帧;使用虚拟时钟进行帧精确录制 |
| 本地开发服务器(我们的) | 对 http://localhost:… 使用相同脚本 | 每次比较中“我们的”一侧,像参考一样精确捕获 |
| 视频 / GIF / 屏幕录制(网页或应用) | ref_frames.py | 以源帧率为基准的每一帧 + 时间/姿态表;从像素测量的值 |
| Figma | figma_fetch.py(令牌)或导出的 PNG 帧 | 精确尺寸、间距、自动布局、排版、颜色、效果、原型过渡 + 参考 PNG |
| 移动应用 | 屏幕录制(参考);对于我们的:xcrun simctl io booted recordVideo ours.mp4(iOS 模拟器)或 adb shell screenrecord(Android) | 作为视频;我们的以相同方式捕获 |
| 组合它们:URL 值 + 用于难以触发的交互(已登录流程、拖动)的录制;Figma 值 + 开发服务器用于检查“我的构建是否与设计匹配”;视频参考 + 用于我们版本的开发服务器捕获。 | ||
| 登录限制页面:要求屏幕录制或让用户登录;切勿处理他们的密码。 |
2. 捕获并测量参考
URL:
inspect_web.mjs --url URL --selector "<section>" --out ui-clone/<name>/ref [--state hover --target "<btn>"]→inspect.md:每个元素的盒子 + 计算样式、声明的过渡、正在运行的动画及其关键帧、@keyframes、字体、检测到的库(GSAP、Framer Motion、Lottie、three.js、Lenis...)、Canvas(2d/WebGL)、悬停/焦点差异。声明的值胜过测量的值:直接复制它们。capture_web.mjs --url URL --selector "<section>" --trigger load|hover|click|scroll|none --duration 2 --fps 30 --out ui-clone/<name>/ref→ frames/、video.mp4、frames.json、animations.json。默认--mode seek(虚拟时钟:JS 定时器和 requestAnimationFrame 基于 Playwright 的时钟,CSS/Web Animations 逐帧暂停和寻找:可得到相同的捕获)。对于虚拟时钟会破坏的页面(视频元素、某些 WebGL/canvas 库),使用--mode realtime并说明原因。--still给出一个用于像素工作的静态截图;--dpr 2用于视网膜级别清晰的比较(小元素使用--dpr 3:12px 的悬停增长在 1x 下像素太少,无法拟合缓动曲线);--pad 12在--selector周围添加边距,以便超出静止盒子边界的悬停/缩放效果仍在画面内;--viewport 390x844用于手机。Seek 模式经证实在多次运行中帧完全相同。--mode realtime以机器允许的最快速度(典型笔记本电脑约 19 帧/秒)截取实时截图并重采样;它会打印实际达到的帧率:时间精度仅受限于该帧率。 视频 / GIF / 录制:ref_frames.py REF.mp4 --out ui-clone/<name>/ref [--start --end --crop x:y:w:h]。 Figma:figma_fetch.py --url "<figma link with node-id>" --out ui-clone/<name>/figma --scale 2→ design.md/json + frame.png。 然后测量运动(任何包含帧的输入):- 切换和章节:
motion_compare.py <ref> <ref> --out <ref>/self --no-align。 - 颜色:
track_motion.py <ref>/frames --sample X,Y --at T。 - 每个移动的元素:
track_motion.py <ref>/frames --name el --colors HEX,HEX --tol 35 --region x,y,w,h(在繁忙的参考上始终使用区域)。 - 每次移动:
fit_easing.py <ref>/track_el.json --prop cx|cy|w|h|aspect|presence --from A --to B→ 时间、缓动、过冲,以及可直接粘贴的 CSS / WAAPI / Framer Motion / GSAP / Remotion 代码行。误差 ≤ 0.03 = 紧密拟合;“没有单独的缓动可以拟合” = 拆分时间窗口或它是关键帧链。当次优方案的误差与最佳方案相差约 0.003 以内时,视为平局(例如,easeOutQuad 0.58 秒与 easeOutCubic 0.80 秒拟合相同的帧):说明这一点,并优先使用inspect.md、源代码或设计图纸中的声明值来打破平局。跟踪仅通过颜色识别元素,因此在移动过程中淡入的元素看起来会延迟开始:对于 Web 输入,改用声明值。 自行阅读每张图纸(sheets/poses.png、sheets/timing_NN.png):数字说明程度,图纸说明内容。
3. 编写规范(ui-clone/<name>/spec.md;每一行都变成一个检查点)
- 结构与静态样式(像素忠实):元素 → 盒子、字体(系列/大小/粗细/行高/字间距)、颜色、圆角、阴影、间距;来源(
inspect.json/design.json/ 测量结果)。 - 时间线(运动):
| # | 元素 | 属性 | 从 → 到 | 开始时间 ms | 持续时间 ms | 缓动 | 交错 / 重复 | 触发 | 来源 |。 - 记录不移动的内容。“?” 表示参考尚未读取。在大型构建之前展示规范。
4. 构建
在用户的栈和设计系统中进行。像素忠实级别精确复制声明的值;运动忠实级别使用相对比例。缓动来自 inspect.json 或 fit_easing.py 针对其库的输出行;如果参考有过冲并稳定下来,则使用弹簧;交错作为 base + index × step。尊重 prefers-reduced-motion(显示结束状态)。将添加的部分放在单独的组件中。为我们的版本提供一个路由/页面,该页面在参考视口中使用相同的触发渲染组件,以便可以相同方式捕获。WebGL 效果:根据参考显示的内容(或者如果用户可能使用,则根据其可读源代码)重建着色器;使用基于时间的固定时间步长和确定性随机数。
5. 验证、修复、重复(2-5 轮;保留每轮文件夹)
- 使用与参考相同的命令捕获我们的版本(仅
--url/输入和--out不同),或者对于视频输入使用ref_frames.py OURS.mp4 --out ui-clone/<name>/ours --like <ref>/frames.json。 - 像素:
screenshot_diff.py <ref>/still.png <ours>/still.png --out ui-clone/<name>/diff-N [--strict] [--max 0.02] [--mask x,y,w,h](像素忠实:始终使用--strict:单像素阈值 0.03,最大 0.5%,任何颜色漂移超过 3 个 RGB 级别的区域均不合格;默认是宽松的,允许小幅内边距和颜色变化通过)→ 差异百分比、最差区域、整图或逐元素偏移(“区域…中的某物移动了 +0 px x, +6 px y”)、颜色漂移、side_by_side.png。先修复偏移(它们会让所有东西看起来都不对劲),然后是大小,最后是颜色。像素忠实模式下任何测量的偏移都导致失败;运动忠实模式使用--allow-shift和更宽松的--max。 - 运动:
motion_compare.py <ref> <ours> --out ui-clone/<name>/compare-N(剪切、移动、偏移;通过条件 ±0.08 秒;activity.png、sheets/compare_NN.png)并且,按规范行,fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK。 - 每轮都阅读图纸。根据证据指向的最小内容进行更改;重新捕获;重新比较。
- 5 轮后,报告每一行仍失败的内容及其数字和原因(字体许可、近似的 WebGL 效果、凭肉眼调节的弹簧)。切勿在未通知的情况下放松阈值。
| 症状 | 通常原因 | 修复 |
|---|---|---|
| 整图偏移 N px | 不同的滚动/偏移/裁剪或缺少包装器边距 | 匹配视口、dpr、裁剪;修复外部间距 |
| 元素移动了 | 外边距/内边距/行高/间距不同 | 将其盒子与 inspect.json / design.json 比较 |
| 所有地方的文本都略有不符 | 后备字体、不同的粗细或字间距 | 加载相同的字体(或用户获得许可的等效字体),匹配大小/粗细/字间距 |
| 所有地方的颜色都略有不符 | 色彩空间、不透明度叠加、渐变停止点 | 复制计算出的颜色/渐变;检查父元素的不透明度 |
| 运动偏移了一个偏移量 | 触发延迟或缺少延迟 | 修复第一个延迟 |
| 我们的版本加载过快 / 过于灵敏 | 更强的缓动(expo 与 cubic 对比) | 使用拟合的贝塞尔曲线或声明的缓动 |
| 参考有过冲,我们没有 | 弹簧/back 与 bezier 对比 | 根据测量的过冲和稳定时间调节弹簧/back |
| 滚动动画开始过早/过晚 | 触发阈值/偏移 | 匹配运动开始的滚动位置 |
| 我们的版本中有一个多余的移动 | 多余的过渡(例如 transition: all) | 将过渡限制在应该动画的属性上 |
6. 报告(必须独立存在)
保真度级别以及克隆/添加的内容;更改的文件以及如何触发运动;最后一轮的表格(像素差异和偏移;剪切/移动时间;逐元素缓动)、side_by_side.png、activity.png 和比较图纸的路径;每一个剩余差异及其数字和原因;哪些检查是测量的(由脚本生成)与目视的(查看图纸)。
限制
- 虚拟时钟捕获无法控制
<video>播放或某些 GPU/物理库:使用--mode realtime并预期 ±1-2 帧的抖动;说明原因。 - 跨域样式表和字体可能会向检查隐藏 @keyframes/@font-face 规则;但仍可读取计算样式和正在运行的动画。
- 从视频中,3D 匹配为相机/物体运动,而非模型或材质;复杂真人场景给出的是节奏,而非精确的元素值。
- 移动端:值来自录制(无源代码);我们版本的模拟器捕获以相同方式进行比较。