html2figma — HTML 原型 ⇄ Figma 可編輯可點擊原型
何時用
- 有現成 HTML 手機原型,要 1:1 搬進 Figma:可編輯圖層 + 可點擊跳屏 + 可滾動 + 常駐層固定。
- 還沒有 HTML 原型:先按 HTML 原型規範 做出來,使用者確認後再進 Figma。
- 修 Figma 原型的疑難:文字重疊/斷行錯誤、reaction 遺失、常駐層跑到長圖底部、不能滾動。
不適用:只有 Figma 檔案、沒有 HTML 來源的原生連線;桌面端靜態設計稿匯入;單純問 Figma 操作怎麼點。
入口三問(不要跳過)
- 有沒有 HTML 原型?
- 有 → 從 Phase 1 開始。
- 沒有 → 走 Phase 0:按規範產出 HTML 原型 → 渲染全部螢幕截圖 → 停下來請使用者確認 → 通過後才進 Figma。HTML 是後續一切幾何與互動的基準,未經確認就匯入,返工成本極高。
- 哪些是「常駐層」?
不要預設是 dock。按 §常駐層判定 掃 DOM/截圖:
position:fixed、或絕對定位錨在視口上下緣、z-index高於內容、在 ≥2 螢幕同一視口座標重複出現。可能是底部 dock、頂部導航、懸浮按鈕 FAB、浮動提示、回到頂端、模態把手等。判不準就看 HTML 行為;HTML 裡也沒有就先問使用者,別猜。 - 交付邊界? 三件都要:①像素還原(無文字重疊/斷行/錯位)②可編輯(Frame/Text/Vector/圖片填充)③可點擊(熱區數量對得上,不是「大約」)。
心智模型(省幾小時的 4 條)
- HTML 是唯一基準。Figma 裡每個改造都要能在 HTML 找到語意:定高視口、
overflow:hidden、position:fixed/absolute、closest('[data-goto]')。 - 匯入 ≠ 還原。外掛給出的是「全高長圖 + 靜態圖層」;視口、滾動、固定層、reaction 都是後處理。
- 能量化就別看圖猜:文字重疊用墨水盒、還原度用 MAE、reaction 用數量稽核、滾動/固定用 Present 截圖序列。
- Figma 外掛 API 能設滾動與固定(實測):
frame.overflowDirection = 'VERTICAL'(合法值只有NONE | VERTICAL | HORIZONTAL | BOTH;傳VERTICAL_SCROLLING之類會報 validation error,別誤讀成「不支援」)。固定子層用numberOfFixedChildren = N,固定層必須是幀的前 N 個子層(先insertChild(0, layer))。Prototype 面板是兜底,以及裝置模型等真正 UI-only 設定的地方。
管線(每階段可獨立驗收)
Phase 0 — 製作 HTML 原型(僅當沒有現成 HTML)
按 references/html-prototype-spec.md:393×852 視口、.phone/.screen/.scroll 結構、data-goto 熱區、設計令牌、內聯 SVG 圖示、字型自包含、clamp 紀律。
完成標準:全部螢幕可渲染、無溢位/壓字、熱區齊全;輸出全螢幕截圖 + 互動說明,讓使用者看圖確認,確認後才繼續。
Phase 1 — 原型體檢
量清楚:螢幕數與尺寸、每螢幕內容高度、-webkit-line-clamp 節點、字型家族/字重、data-goto 去重後的有效熱區數、常駐層清單(見 §常駐層判定)。
產物:boards.json、hotspots.json、clamp.json、persistent.json。
Phase 2 — Feed 構建(畫布 → 可匯入的單串流)
注入 CSS/JS 後序列化 feed/index.html:
- 隱藏畫布外殼(頂欄/側欄/螢幕標籤/網格);
- UNCLIP:去掉定高與
overflow:hidden,讓內容自然展開(後續按全高取圖層、再裁回視口); - 截斷策略(先試原生,再考慮烘焙):匯入後可對文字層設
textTruncation='ENDING'+maxLines=N(寫之前必須loadFontAsync)。只有需要與瀏覽器逐字一致的斷行時才在 feed 裡烘焙 clamp(演算法見 pipeline)。完全不做截斷會畫出框外壓字; data-h2f-name命名板與常駐層;字型@font-face內聯/自包含。
Phase 3 — 字型精確命中(斷行還原的關鍵)
對原型實際字型做子集化 + 改名加統一前綴 + 安裝(HKCU/系統字型)。Figma 必須命中同名字型,否則替換會製造假「斷行錯誤」。命令與改名腳本見 pipeline。
Phase 4 — 匯入與拆板
上游安裝:git clone https://github.com/kevicebryan/open-htmltofigma.git,Figma 桌面 → Plugins → Development → Import plugin from manifest…(選倉庫內 manifest.json);固定 commit/tag,manifest id 衝突時改掉。外掛在 iframe 真實渲染 feed → 直建 Frame/Text/Vector;本地注入腳本自動填寫並 Convert(匯入前把外掛視口設成 393×852,否則 vh/媒體查詢會按預設 1440×1024 解析)。匯入後把每螢幕 Frame 提升為頂層、橫排、命名 NN id · 標題,刪根容器。匯入器不建立任何 reaction,必須按 Phase 5 重寫;外掛版本要固定(見 pipeline)。
Phase 5 — 互動(reaction)
按面積升序遍歷熱區;bbox ±2 命中最小非 TEXT 節點,中心點兜底;節點不支援 reaction 就沿祖先上爬;已有 reaction 是繼續上爬的理由(父熱區掛自己節點),不是終止條件;自跳跳過。讀 node.reactions,寫 await setReactionsAsync()。
寫完用同一套命中+上爬邏輯回放,exp == ok && wrong == 0;數量稽核要求 dangling == 0。
Phase 6 — 視口化 + 常駐層定位
先用 persistent.json 列出每個常駐層的錨點判定(bottom/top/fab/none)和依據,再動手;不確定的標出來問使用者,不要預設全固定。
原地把每板改成原型視口尺寸(如 393×852;從 .phone 實測讀取,不要寫死,Android 常見 360×800/412×915),resize + clipsContent,把常駐層從內容層提到板根,按視口錨點定位:
- 底部條:
y = 視口高 - 高度; - 頂部條:
y = 0; - 右下 FAB:按 HTML 的
right/bottom換算; - 可隱藏/自動收起類(滾動時淡出的頂欄):不要固定,保留內容串流語意。
固定與滾動可以直接走 API(本專案實測,Figma 桌面版):
board.insertChild(0, layer); // 固定層必須排在子層最前
board.numberOfFixedChildren = 1; // 前 N 個子層 = 固定層
board.overflowDirection = 'VERTICAL';
UI 的 Position = Fixed 與 Overflow = Vertical 語意相同,可作兜底。要保留 reaction 就不要把板複製到別的頁:跨頁 setReactionsAsync 實測全失敗。先複製全高板到 ARCHIVE 頁歸檔,再原地重構。
Phase 7 — 滾動 + 固定 + 裝置模型
- 滾動:
board.overflowDirection = 'VERTICAL'(列舉只有NONE | VERTICAL | HORIZONTAL | BOTH); - 固定:
board.numberOfFixedChildren = N(固定層=前 N 個子層,見 Phase 6); - UI 兜底:多選板 → Prototype →
Overflow = Vertical;多選常駐層 →Position = Fixed (stay in place); - 裝置模型(UI-only):取消選取 → 檔案級 Prototype 設定 → Device 選與原型同尺寸的裝置(如 iPhone 15 Pro = 393×852);首頁設 Flow starting point。 理由與座標細節見 figma-ui-and-automation。
Phase 8 — 三層驗收
- 像素:2x 匯出 vs 參考,按
@dx,dy裁陰影溢位 + ±2px 搜尋,MAE 3–10 正常; - 互動:reaction 稽核 + 回放驗證;
- 演示:Present 三連截圖(初始 / 滾動後 / 跳屏後),確認常駐層始終在視口內、不隨內容移動。 細節與閾值見 verification。
常駐層判定(重要,不要只認 dock)
判定訊號(滿足任意兩條即候選):
| 訊號 | 怎麼看 |
|---|---|
| CSS 定位 | position:fixed,或 absolute + bottom/top 貼視口緣 |
| 層級 | z-index 高於內容層;覆蓋在滾動內容之上 |
| 跨螢幕重複 | 同一選取器/同一視口座標在 ≥2 螢幕出現(底部導航、頂欄最常見) |
| 視覺 | 圓角懸浮條、毛玻璃、陰影浮層、FAB、toast |
| 行為 | HTML/JS 裡監聽滾動做 show/hide 或變色 |
處理決策:
- 始終覆蓋、跨螢幕常駐(底部 tab 欄、頂欄)→ Figma 視口內固定(
Fixed)。 - 只覆蓋不吸頂(FAB)→ 同樣提到視口層並固定。
- 隨內容滾走(普通卡片、內聯按鈕)→ 留在內容層,不要固定。
- 滾動時隱藏/出現(auto-hide header)→ Figma 無法用原生互動復現完整邏輯:優先保持「滾動跟隨/隱藏」的靜態語意,或拆成狀態螢幕;不要錯誤地設成 Fixed。判不準就問使用者想要哪種演示效果。
- 彈層/模態把手 → 通常屬於彈層螢幕本身,按該螢幕內容處理,不跨螢幕固定。
本專案實例:底部 dock 14 螢幕各 6 個熱區,提到
y = 852-72 = 780後設 Fixed;同一套公式對頂欄/FAB 適用——先判定語意,再套座標。
高頻坑(Top 14)
| # | 現象 | 根因 / 對策 |
|---|---|---|
| 1 | 常駐層在長圖最底下 | 匯入 UNCLIP 把定高視口展開,bottom:0 落到內容末尾 → Phase 6 視口化 |
| 2 | 設滾動報 validation error | 列舉值寫錯(如 VERTICAL_SCROLLING)→ 用 VERTICAL;普通 FRAME 可寫,別誤判成不支援 |
| 3 | 固定子層設了沒生效 | 固定層必須是幀的前 N 個子層:先 insertChild(0, layer) 再設 numberOfFixedChildren = N |
| 4 | 複製到新頁後 reaction 全失敗 | 跨頁 setReactionsAsync 被拒 → 原地重構,歸檔另存 |
| 5 | 文字壓住下方標籤 | 先試原生 textTruncation='ENDING' + maxLines;仍不一致再在 feed 烘焙逐字截斷 |
| 6 | Figma 斷行與瀏覽器不同 | 字型被替換 → 子集化+改名+安裝 |
| 7 | 匯出圖比畫板大、比對全錯 | 匯出含陰影溢位 → 按 @dx,dy 裁剪 |
| 8 | 合成滑鼠點擊/滾輪無效 | webview 過濾;選單可點。面板用 UIA/鍵盤;播放器滾動用 PostMessage 滾輪 |
| 9 | 彈層第二次腳本點擊落空 | 每次執行會重新前景化 → 開啟+選取放同一次執行 |
| 10 | 截圖座標漂移 | DPI 感知;截圖座標 == 視窗相對座標;UIA 是絕對物理像素 |
| 11 | 外掛跑進別的檔案 | Figma 還原舊標籤/誤開 Untitled → 先確認啟用標籤 |
| 12 | 裁剪圖打不開 | 非整數縮放產生小數尺寸 → 輸出取整 |
| 13 | 畫布多出奇怪文字 | 誤貼上產生 TEXT 節點 → 按內容正則清理 |
| 14 | 結果讀不到 | 用 page.name 或本機 HTTP 收集器做狀態回讀 |
平台與相容性
- 本 skill 遵循 Agent Skills 規範(SKILL.md + references/ + scripts/),ZCode、Claude Code 及任何實現該規範的 agent 均可載入。
- 流程描述盡量通用,但匯入環節依賴 open-htmltofigma 開發外掛與 Figma 桌面端,自動化腳本面向 Windows;macOS/Linux 用 AppleScript/
screencapture/xdotool等改寫,或按文件手動操作。 - Figma 網頁版不能匯入本機開發外掛;外掛相關步驟需桌面端(網頁版可開啟已發佈的外掛)。
參考與腳本
- references/html-prototype-spec.md — 沒有 HTML 原型時的製作規範與驗收清單(含「先給使用者看」的門禁)。
- references/pipeline.md — feed/UNCLIP、clamp 演算法、字型、匯入拆板、reaction、視口化程式碼骨架。
- references/figma-ui-and-automation.md — API/UI 能力矩陣、批次設定、裝置模型、Windows 自動化與座標規則。
- references/verification.md — MAE、reaction 稽核/回放、Present 三連、失敗分診。
scripts/rename_font.py、scripts/install_font.ps1— 字型子集化/改名與目前使用者安裝(含解除安裝)。scripts/figma_win.ps1、scripts/uia.ps1— Windows 輔助(點擊/懸停/按鍵/滾輪/截圖、UIA 列舉/點擊/聚焦)。scripts/crop.mjs— 跨平台 PNG 裁剪(整數縮放,截圖審查用)。
工作方式
- 改程式碼前說明「改哪一行、為什麼」,一次一個根因;中間產物帶版本號新檔案名。
- 每個「看起來對」都要有數字或截圖證據;每個「應該能」都要在 Present 實測。
- 只圍繞「還原 / 可編輯 / 可點擊」三件事,不順手重構管線、不升級相依套件。