Communitygithub.com

html2figma — HTML 原型 ⇄ Figma 可编辑可点击原型

將 HTML 手機原型轉換為可編輯、可點擊、可滾動的 Figma 原型,或先製作 HTML 原型再導入,支援多屏電路板、向量圖層、ON_CLICK 跳轉反應、設備模型、常駐層偵測、真實滾動與像素級還原驗證。

html2figma — HTML 原型 ⇄ Figma 可编辑可点击原型 是什麼?

這個技能(html2figma)讓 AI 代理能將 HTML 手機原型(Phone Prototype)完整轉換為 Figma 中的可編輯、可互動原型。當使用者已有基於標準手機視口(例如 393×852)的 HTML 原型時,此技能會將其 Figma 資源轉換為可點擊跳轉的多螢幕原型的圖層結構,並確保文字不斷行、陰影不溢位、視口正確裁剪,以及關鍵的常駐層(如底部導航欄、頂部欄、浮動按鈕、Toast)固定在視口內。它支援的一次性解決方案涵蓋了從 HTML 原型製作(Phase 0)到 Figma 導入、互動綁定(REACTION)、視口化與滾動設定的完整管道。此技能特別關注 Figma API 的使用(如 `overflowDirection` 與 `numberOfFixedChildren`)和常見的陷阱(例如字型替換造成的斷行錯誤、克隆頁面造成 REACTION 失效、導出截圖因陰影溢出而定位錯位),並提供了一套基於真實數據的驗證方法(普朗姆差異度、互動審計、截圖序列)。其設計目的是讓設計師和 AI 代理以最少的迭代次數獲得高品質、可直接用於測試與協作的 Figma 原型,避免手動重複造輪。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilovemajiaqi/html2figma/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

html2figma — HTML 原型 ⇄ Figma 可編輯可點擊原型

何時用

  • 有現成 HTML 手機原型,要 1:1 搬進 Figma:可編輯圖層 + 可點擊跳屏 + 可滾動 + 常駐層固定。
  • 還沒有 HTML 原型:先按 HTML 原型規範 做出來,使用者確認後再進 Figma。
  • 修 Figma 原型的疑難:文字重疊/斷行錯誤、reaction 遺失、常駐層跑到長圖底部、不能滾動。

不適用:只有 Figma 檔案、沒有 HTML 來源的原生連線;桌面端靜態設計稿匯入;單純問 Figma 操作怎麼點。

入口三問(不要跳過)

  1. 有沒有 HTML 原型?
    • 有 → 從 Phase 1 開始。
    • 沒有 → 走 Phase 0:按規範產出 HTML 原型 → 渲染全部螢幕截圖 → 停下來請使用者確認 → 通過後才進 Figma。HTML 是後續一切幾何與互動的基準,未經確認就匯入,返工成本極高。
  2. 哪些是「常駐層」? 不要預設是 dock。按 §常駐層判定 掃 DOM/截圖:position:fixed、或絕對定位錨在視口上下緣、z-index 高於內容、在 ≥2 螢幕同一視口座標重複出現。可能是底部 dock、頂部導航、懸浮按鈕 FAB、浮動提示、回到頂端、模態把手等。判不準就看 HTML 行為;HTML 裡也沒有就先問使用者,別猜。
  3. 交付邊界? 三件都要:①像素還原(無文字重疊/斷行/錯位)②可編輯(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 — 三層驗收

  1. 像素:2x 匯出 vs 參考,按 @dx,dy 裁陰影溢位 + ±2px 搜尋,MAE 3–10 正常;
  2. 互動:reaction 稽核 + 回放驗證;
  3. 演示: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 烘焙逐字截斷
6Figma 斷行與瀏覽器不同字型被替換 → 子集化+改名+安裝
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 實測。
  • 只圍繞「還原 / 可編輯 / 可點擊」三件事,不順手重構管線、不升級相依套件。

相關技能