Communitygithub.com

ui-clone

用於前端工作,當使用者想要從參考來源(包含網址、本機開發伺服器、影片、GIF、螢幕錄影或 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-clone 是什麼?

這個 UI 複製(ui-clone)技能提供一套系統化方法,用於從多種參考來源(即時網頁、本機開發伺服器、影片/GIF/螢幕錄影、Figma 設計)精確複製使用者介面、動畫與特效,並在使用者的技術棧中重建,最後透過自動化腳本驗證相符程度。它透過「捕捉參考 → 測量精確值 → 撰寫規格 → 建構 → 捕捉自己的結果 → 比較 → 修正」的迴圈,確保輸出不只是「看起來差不多」,而是附有數據、差異影像與並排比對表的可驗證程式碼。此技能支援多種精確度等級(像素忠實、動態忠實、混合),並提供 Playwright 虛擬時鐘擷取、影片逐幀分析、Figma API 擷取、動態比對與緩動函數擬合等工具,可適用於 Cursor、Claude Code、Codex 等 AI 代理平台。開發者需先完成一次性的 Python 虛擬環境、Playwright 及 ffmpeg 設定。

相容平台~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,僅用於網址 / 開發伺服器輸入):執行器位於 ~/.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 頂端,在任何擷取之前)

  • 目標:明確指定要複製的內容(網址 + 選取器、檔案 + 時間範圍 + 裁切、Figma 節點),不多不少。
  • 精確度(在首次回覆中陳述;它決定要驗證的項目):
    等級適用時機必須相符可容差異
    動態忠實(他人作品預設值)「讓我們的感覺/動作像他們的」結構與比例、順序、時間 ±0.08 秒、緩動類型、超調量、相對於尺寸的移動距離、交錯文案、色彩、字型、圖片、品牌
    像素忠實使用者自己的設計(Figma → 程式碼)、自己的網站、客戶工作(擁有權限)或私人練習以上所有項目 + 字型、尺寸、間距、色彩、圓角、陰影、素材;螢幕截圖不符 ≤ 2%(靜止狀態 ≤ 0.5%),無任何可測量的位移他們未要求更改的任何內容
    混合「複製 X 並加入 Y」被複製的部分需符合上述其中一個等級新增的部分(分開存放、顯示、並檢查不會破壞複製部分)
  • 權利:其他公司的 UI、標誌、插圖、字型與文案的像素忠實複製版本屬於他們;僅供學習或經許可時使用,且切勿將其發布為使用者自己的作品。當參考來源是第三方產品且使用者希望發布時,預設使用動態忠實等級並搭配自己的設計,同時說明原因。
  • 目的地:程式碼的放置位置與所使用的技術棧。閱讀 package.json、現有元件、樣式系統(Tailwind 設定檔、CSS 變數、設計令牌)以及已使用的動畫函式庫;與其匹配,而非新增一個新函式庫。

1. 選擇輸入方式(使用最精確的方式;說明你使用哪一種)

輸入擷取方式取得的內容
即時網址inspect_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)如同影片;我們的結果以相同方式擷取

可組合使用:網址值 + 適用於難以觸發的互動(需登入的流程、拖曳)的錄影;Figma 數值 + 開發伺服器用來檢查「我的建構是否匹配設計」;影片參考 + 開發伺服器擷取作為我們的結果。需要登入的頁面:要求提供螢幕錄影或請使用者自行登入;絕不處理他們的密碼。

2. 捕捉並測量參考

網址:

  • 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:12 px 的懸停增長在 1x 下幀數太少,無法準確擬合緩動);--pad 12 可在 --selector 周圍添加邊距,使可能超出靜止方塊的懸停/縮放效果保持在畫面內;--viewport 390x844 適用於手機。 尋址模式經驗證可在多次執行中產生相同的幀。--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、原始碼或比對表中的宣告值來打破平手。追蹤僅能透過元素顏色來識別,因此在移動過程中淡入的元素看起來會「晚開始」:對於網頁輸入,請改用宣告值。 請親自閱讀每一張比對表(sheets/poses.png、sheets/timing_NN.png):數字說明有多,比對表說明是什麼。

3. 撰寫規格(ui-clone/<name>/spec.md;每一行都將成為一項檢查)

  • 結構與靜態樣式(像素忠實):元素 → 盒模型、字型(系列/大小/粗細/行高/字距)、色彩、圓角、陰影、間距;來源(inspect.json / design.json / 測量值)。
  • 時間軸(動態):| # | 元素 | 屬性 | 從 → 到 | 開始毫秒 | 持續時間毫秒 | 緩動 | 交錯 / 重複 | 觸發 | 來源 |。
  • 註明哪些項目沒有移動。若出現「?」表示尚未讀取參考。在進行大型建構之前,請先展示規格。

4. 建構

在使用者的技術棧與設計系統中進行。精確複製宣告值(像素忠實)或相對比例(動態忠實)。緩動函數取自 inspect.json 或 fit_easy.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 像素不同的滾動/偏移/裁切或缺少外層 wrapper 邊距匹配視口、dpr、裁切;修正外層間距
某個元素移動了margin/padding/line-height/gap 不同將其盒模型與 inspect.json / design.json 比較
所有文字都略有偏移後備字型、不同粗細或字距載入相同字型(或使用者已授權的等效字型),匹配大小/粗細/字距
所有色彩都略有偏差色彩空間、透明度疊加、漸層停止點複製計算後的色彩/漸層;檢查父元素的透明度
動態整體偏移一個間隔觸發延遲或缺少延遲修正第一個延遲
我們的動態偏早 / 太快較強的緩動(expo vs cubic)使用擬合後的貝茲曲線或宣告的緩動
參考有超調,我們沒有彈簧/back 與貝茲曲線的差異根據測量到的超調與穩定時間調整彈簧/back
滾動動畫過早/過晚開始觸發閾值/偏移匹配動態開始時的滾動位置
我們的結果中有額外的動畫意外的轉場(例如 transition: all)將轉場限制在應有動畫的屬性上

6. 報告(必須能獨立解釋一切)

精確度等級及複製/新增的內容;修改的檔案與如何觸發動態;最後一輪的表格(像素不符與位移;剪輯/移動時間;每個元素的緩動),side_by_side.png、activity.png 及比較表的路徑;每一項剩餘差異及其數值與原因;哪些檢查是經由腳本測量的,哪些是目測的(檢視比對表)。

限制

  • 虛擬時鐘擷取無法控制 <video> 播放或某些 GPU/物理函式庫:請使用 --mode realtime,並預期 ±1-2 幀的抖動;請說明。
  • 跨來源樣式表與字型可能會隱藏 @keyframes/@font-face 規則,使其無法被檢視;計算後的樣式與正在執行的動畫仍可讀取。
  • 從影片中,3D 會以攝影機/物體運動的形式匹配,而非模型或材質;複雜的實拍畫面僅提供節奏,而非精確元素值。
  • 行動裝置:數值來自錄影(無原始碼);我們透過模擬器擷取的結果以相同方式進行比較。

相關技能