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 | 原始幀率下的每一幀 + 時間/姿勢表;從像素測量數值 |
| Figma | figma_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 輪;保留每一輪的資料夾)
- 使用與參考相同的指令(僅更改
--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 像素 | 不同的滾動/偏移/裁切或缺少外層 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 會以攝影機/物體運動的形式匹配,而非模型或材質;複雜的實拍畫面僅提供節奏,而非精確元素值。
- 行動裝置:數值來自錄影(無原始碼);我們透過模擬器擷取的結果以相同方式進行比較。