Communitygithub.com

UI 克隆

用于前端工作,当用户想要从参考源(实时 URL、本地开发服务器、视频、录屏或 Figma 设计)克隆、复制、重建或匹配某个 UI、区块、组件、效果或动画时。覆盖像素级精确 UI(布局、字体、间距、颜色)、动画和交互(加载、悬停、点击、滚动、页面过渡、加载器、跑马灯、弹簧),以及效果(渐变、模糊、着色器、Canvas/WebGL 背景),在用户的栈(HTML/CSS、React、Next.js、Vue、Svelte、Tailwind、Framer Motion、GSAP、Web Animations、three.js、React Native、SwiftUI)中重建,然后通过截图差异和逐帧时间与参考进行验证。不适用于用户纪录片频道的视频(documentary-animation)或纯视频运动研究(motion-match)。

UI 克隆 是什么?

UI 克隆是一个 AI 智能体技能,用于前端工作中高精度地复制 UI 元素、动画和效果。它遵循一个系统化的循环:捕获参考→测量(尽可能读取精确值,否则测量像素)→编写规范→在用户的栈中构建→以相同方式捕获我们的结果→比较→修复,直到规范通过。该技能支持多种输入源:实时 URL(通过 Playwright 捕获,支持虚拟时钟实现帧精确录制)、本地开发服务器、视频/GIF/屏幕录制(使用 ffmpeg 提取帧)、Figma 设计(需要令牌),以及移动应用(通过模拟器/设备录制)。它生成代码和**证据**(数字、差异图像、并排对比表),确保不仅仅是“看起来差不多”。该技能定义了三种保真度级别:**运动忠实**(使运动感觉/行为像参考,但允许设计差异)、**像素忠实**(像素级精确匹配,静止状态下截图差异≤0.5%)和**混合**(克隆部分采用一种级别,添加部分单独保留)。验证过程严格:使用 `screenshot_diff.py` 进行像素比较(像素忠实级别严格模式),使用 `motion_compare.py` 和 `fit_easing.py` 进行运动比较(容差±0.08秒),并且每轮修复都会迭代 2-5 轮。该技能在用户的项目结构内创建隔离的 `ui-clone/<name>/` 文件夹,并包含 ref/、ours/、compare-N/、diff-N/ 和 spec.md 等子文件夹。它会读取用户的 `package.json`、现有组件、样式系统和动画库,以匹配现有代码,避免添加新库。该技能尊重用户权利:默认情况下,第三方产品参考采用运动忠实级别,像素忠实级别仅用于用户自己的设计或获得许可的作品。它还包括处理常见问题(如全图偏移、文本渲染差异、时间偏移)的调试表格。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/stazdev/ui-clone/tree/HEAD/skills/ui-clone

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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. 选择输入方法(最精确的可用方法;说明你使用哪一个)

输入捕获你得到什么
实时 URLinspect_web.mjs + capture_web.mjs精确的 CSS 值、字体、声明的持续时间/延迟/缓动、关键帧;使用虚拟时钟进行帧精确录制
本地开发服务器(我们的)对 http://localhost:… 使用相同脚本每次比较中“我们的”一侧,像参考一样精确捕获
视频 / GIF / 屏幕录制(网页或应用)ref_frames.py以源帧率为基准的每一帧 + 时间/姿态表;从像素测量的值
Figmafigma_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 轮;保留每轮文件夹)

  1. 使用与参考相同的命令捕获我们的版本(仅 --url/输入和 --out 不同),或者对于视频输入使用 ref_frames.py OURS.mp4 --out ui-clone/<name>/ours --like <ref>/frames.json。
  2. 像素: 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。
  3. 运动: 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。
  4. 每轮都阅读图纸。根据证据指向的最小内容进行更改;重新捕获;重新比较。
  5. 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 匹配为相机/物体运动,而非模型或材质;复杂真人场景给出的是节奏,而非精确的元素值。
  • 移动端:值来自录制(无源代码);我们版本的模拟器捕获以相同方式进行比较。

相关技能