html2figma — HTML プロトタイプ ⇄ Figma 編集可能・クリック可能プロトタイプ
使用タイミング
- 既存の HTML モバイルプロトタイプを Figma に 1:1 で移植したい場合:編集可能レイヤー + クリックで画面遷移 + スクロール + 永続レイヤーの固定。
- HTML プロトタイプがまだない場合:まず HTML プロトタイプ仕様 に従って作成し、ユーザーが確認してから Figma に進みます。
- Figma プロトタイプのトラブルシューティング:テキストの重なり・改行の誤り、リアクションの欠落、永続レイヤーが長いフレームの下部に落ちる、スクロールできない。
適用外:Figma ファイルのみで HTML ソースがないネイティブな画面遷移;デスクトップ向け静的デザインのインポート;Figma の操作方法に関する単発の質問。
最初の 3 つの質問(スキップしない)
- HTML プロトタイプはありますか?
- ある → Phase 1 から開始。
- ない → Phase 0 へ:仕様に従って HTML プロトタイプを作成 → 全画面のスクリーンショットをレンダリング → 一旦停止してユーザーに確認依頼 → 承認後、Figma に進む。HTML は以降のすべての形状とインタラクションの基準であり、確認なしでインポートすると手戻りコストが非常に高くなる。
- 「永続レイヤー」はどれですか?
デフォルトでドックと決めつけない。§永続レイヤーの判定 に従い DOM/スクリーンショットをスキャン:
position:fixed、またはビューポートの上下端に絶対配置されている、z-indexがコンテンツより高い、2 画面以上で同じビューポート座標に繰り返し出現する。ボトムドック、トップナビゲーション、フローティングアクションボタン (FAB)、フローティング通知、トップへ戻るボタン、モーダルハンドルなどが該当する。判定が不確かな場合は HTML の動作を確認する;HTML にもない場合はユーザーに尋ね、推測しない。 - 成果物の境界は? 3 つすべてが必要:① ピクセル単位の再現(テキストの重なり・改行ずれ・位置ずれがない)② 編集可能(フレーム/テキスト/ベクター/画像フィル)③ クリック可能(ホットスポットの数が一致していること、「おおよそ」ではダメ)。
メンタルモデル(数時間を節約する 4 つの原則)
- HTML が唯一の基準である。Figma でのあらゆる改造は、HTML に意味的対応関係が見つかる必要がある:固定高さビューポート、
overflow:hidden、position:fixed/absolute、closest('[data-goto]')。 - インポート ≠ 再現。プラグインが提供するのは「全高の長い画像+静的レイヤー」であり;ビューポート、スクロール、固定レイヤー、リアクションはすべて後処理で追加される。
- 定量化できるなら、見た目で推測しない:テキストの重なりはバウンディングボックスで、再現精度は MAE で、リアクションは数で監査し、スクロール/固定は Present のスクリーンショット系列で確認する。
- Figma プラグイン API でスクロールと固定は設定可能(実証済み):
frame.overflowDirection = 'VERTICAL'(有効な値はNONE | VERTICAL | HORIZONTAL | BOTHのみ;VERTICAL_SCROLLINGなどを渡すとバリデーションエラーになるので、「サポートされていない」と誤解しないこと)。固定子レイヤーはnumberOfFixedChildren = Nで設定する。固定レイヤーはフレームの先頭 N 個の子レイヤーでなければならない(最初にinsertChild(0, layer)を実行する)。プロトタイプパネルは最後の手段であり、デバイスモデルなど本当に UI のみで設定する項目に使用する。
パイプライン(各フェーズで独立して検証可能)
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 — フィードの構築(キャンバス → インポート可能な単一画面ストリーム)
CSS/JS を注入した後、feed/index.html をシリアライズする:
- キャンバスの外枠(トップバー/サイドバー/画面ラベル/グリッド)を非表示にする;
- UNCLIP:固定高さと
overflow:hiddenを解除し、コンテンツを自然に展開させる(後で全高でレイヤーを取得し、ビューポートサイズにトリミングする); - テキスト切り詰め戦略(まずネイティブを試し、次にベイクを検討):インポート後、テキストレイヤーに
textTruncation='ENDING'+maxLines=Nを設定できる(事前にloadFontAsyncを呼び出すこと)。ブラウザと一字一句一致する改行が必要な場合のみ、フィード内で 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 内でフィードを実際にレンダリングし、Frame/Text/Vector を直接作成する;ローカルインジェクションスクリプトが自動的に入力を実行して Convert する(インポート前にプラグインビューポートを 393×852 に設定しておくこと。そうしないと vh/メディアクエリがデフォルトの 1440×1024 で解釈される)。インポート後、各画面の Frame をトップレベルに昇格させ、横に並べ、NN id · タイトル の形式で名前を付け、ルートコンテナを削除する。インポーターはいかなるリアクションも作成しない。 必ず Phase 5 に従って書き直すこと;プラグインのバージョンは固定する(pipeline 参照)。
Phase 5 — インタラクション(リアクション)
ホットスポットを面積の昇順で走査する;bbox ±2px 以内で最小の非 TEXT ノードをヒットさせ、中心点をフォールバックとする;ノードがリアクションをサポートしていない場合は祖先を遡る;既存のリアクションは遡る理由になる(親ホットスポットが自身のノードを保持しているため)、終了条件ではない;自身への遷移はスキップする。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 は同じ意味であり、フォールバックとして使用できる。リアクションを保持するには、ボードを別のページにクローンしないこと:ページをまたぐ 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 のみ):選択を解除 → ファイルレベルの Prototype 設定 → Device でプロトタイプと同じサイズのデバイスを選択(例:iPhone 15 Pro = 393×852);最初の画面に Flow starting point を設定する。 理由と座標の詳細は figma-ui-and-automation を参照。
Phase 8 — 3 層検証
- ピクセル:2x 書き出しと参照画像を比較、
@dx,dyに従ってシャドウのはみ出しをトリミングし、±2px で検索、MAE 3–10 が正常範囲。 - インタラクション:リアクション監査 + リプレイ検証。
- プレゼンテーション:Present で 3 枚のスクリーンショットを撮影(初期状態 / スクロール後 / 画面遷移後)、永続レイヤーが常にビューポート内にあり、コンテンツと一緒に移動していないことを確認。 詳細と閾値は verification を参照。
永続レイヤーの判定(重要:ドックだけを認識しない)
判定シグナル(任意の 2 つに該当で候補):
| シグナル | 確認方法 |
|---|---|
| CSS 配置 | position:fixed、または absolute + bottom/top がビューポート端に接している |
| 階層 | z-index がコンテンツレイヤーより高い;スクロールコンテンツの上に重なっている |
| 画面跨ぎの繰り返し | 同じセレクタ/同じビューポート座標が 2 画面以上に出現する(ボトムナビゲーション、トップバーが最も一般的) |
| 視覚的特徴 | 角丸のフローティングバー、すりガラス効果、シャドウのあるフローティング要素、FAB、トースト |
| 動作 | HTML/JS でスクロールをリッスンして表示/非表示や色変更を行っている |
処理の決定:
- 常に重なり、画面を跨いで永続的(ボトムタブバー、トップバー)→ Figma ビューポート内で固定(
Fixed)。 - 重なるが画面上端に固定されない(FAB)→ 同様にビューポートレイヤーに移動し固定。
- コンテンツとともにスクロールする(通常のカード、インラインボタン)→ コンテンツレイヤーに残し、固定しない。
- スクロール時に非表示/表示される(auto-hide header)→ Figma のネイティブインタラクションでは完全なロジックを再現できない:優先的に「スクロールに追従/非表示」の静的セマンティクスを維持するか、状態別の画面に分割する;誤って Fixed に設定しない。判定が不確かな場合は、ユーザーに希望するプレゼンテーション効果を確認する。
- ポップアップ/モーダルハンドル → 通常はポップアップ画面自体に属するため、その画面のコンテンツとして処理し、画面を跨いで固定しない。
本プロジェクトの実例:ボトムドックは 14 画面で各 6 個のホットスポットを持ち、
y = 852-72 = 780に移動後 Fixed を設定;同じ公式がトップバー/FAB にも適用可能 — まずセマンティクスを判定し、次に座標を適用する。
高頻度の落とし穴(トップ 14)
| # | 現象 | 根本原因 / 対策 |
|---|---|---|
| 1 | 永続レイヤーが長い画像の最下部にある | インポート時の UNCLIP で固定高さビューポートが展開され、bottom:0 がコンテンツ末尾に落ちる → Phase 6 のビューポート化で対応 |
| 2 | スクロール設定でバリデーションエラー | 列挙値の誤り(例:VERTICAL_SCROLLING)→ VERTICAL を使用;通常の FRAME でも設定可能なので「サポートされていない」と誤判定しない |
| 3 | 固定子レイヤーを設定したが効果がない | 固定レイヤーはフレームの先頭 N 個の子レイヤーでなければならない:まず insertChild(0, layer) を実行し、その後 numberOfFixedChildren = N を設定する |
| 4 | 新しいページにクローンした後、リアクションがすべて失敗 | ページをまたぐ setReactionsAsync が拒否される → 元の場所で再構築し、アーカイブは別途保存 |
| 5 | テキストが下のラベルを押しつぶす | まずネイティブの textTruncation='ENDING' + maxLines を試す;それでも一致しない場合のみ、フィード内で一字一句のテキスト切り詰めをベイクする |
| 6 | Figma の改行がブラウザと異なる | フォントが置き換えられている → サブセット化+リネーム+インストール |
| 7 | 書き出した画像がアートボードより大きく、比較がすべてずれる | 書き出しにシャドウのはみ出しが含まれている → @dx,dy に従ってトリミング |
| 8 | 合成マウスクリック/ホイールが機能しない | webview がフィルタリングする;メニューはクリック可能。パネルは UIA/キーボードを使用;プレイヤーのスクロールは PostMessage ホイールを使用 |
| 9 | ポップアップへの 2 回目のスクリプトクリックが失敗する | 毎回の実行でウィンドウが最前面に移動される → 開く+選択を同じ実行内で行う |
| 10 | スクリーンショットの座標がずれる | DPI を認識すること;スクリーンショット座標 == ウィンドウ相対座標;UIA は絶対物理ピクセル |
| 11 | プラグインが別のファイルで実行される | Figma が古いタブを復元したり、Untitled を誤って開いたりする → まずアクティブタブを確認する |
| 12 | トリミングした画像が開けない | 非整数の拡大縮小で小数サイズが生成される → 出力を整数に丸める |
| 13 | キャンバスに奇妙なテキストが現れる | 誤ってペーストされた TEXT ノード → 内容を正規表現でクリーンアップする |
| 14 | 結果が読み取れない | page.name またはローカル HTTP コレクターを使用してステータスを読み戻す |
プラットフォームと互換性
- 本スキルは Agent Skills 仕様(SKILL.md + references/ + scripts/)に準拠しており、ZCode、Claude Code、およびこの仕様を実装する任意のエージェントで読み込むことができます。
- フローの説明は可能な限り汎用的にしていますが、インポート部分は** open-htmltofigma 開発プラグインと Figma デスクトップ版に依存**しています。自動化スクリプトは Windows を対象としています;macOS/Linux の場合は、AppleScript/
screencapture/xdotoolなどで書き換えるか、ドキュメントに従って手動で操作してください。 - Figma Web 版ではローカル開発プラグインをインポートできません;プラグイン関連の手順はデスクトップ版が必要です(Web 版では公開済みプラグインを開くことは可能です)。
参考資料とスクリプト
- references/html-prototype-spec.md — HTML プロトタイプがない場合の作成仕様と受け入れチェックリスト(「まずユーザーに見せる」ゲートを含む)。
- references/pipeline.md — feed/UNCLIP、clamp アルゴリズム、フォント、インポートとボード分割、リアクション、ビューポート化のコードスケルトン。
- references/figma-ui-and-automation.md — API/UI 機能マトリクス、一括設定、デバイスモデル、Windows 自動化と座標ルール。
- references/verification.md — MAE、リアクション監査/リプレイ、Present 3 連ショット、障害トリアージ。
scripts/rename_font.py、scripts/install_font.ps1— フォントのサブセット化/リネームとカレントユーザーへのインストール(アンインストールを含む)。scripts/figma_win.ps1、scripts/uia.ps1— Windows 支援(クリック/ホバー/キー操作/ホイール/スクリーンショット、UIA 列挙/クリック/フォーカス)。scripts/crop.mjs— クロスプラットフォーム PNG トリミング(整数拡大縮小、スクリーンショットレビュー用)。
作業方法
- コードを変更する前に「どの行を、なぜ変更するか」を説明し、一度に一つの根本原因に対処すること;中間生成物にはバージョン番号を含む新しいファイル名を付けること。
- 「正しく見える」すべてのものについて、数値またはスクリーンショットによる証拠が必要;「おそらくできる」すべてのものについて、Present で実際にテストすること。
- 「再現性 / 編集可能性 / クリック可能性」の 3 つのみに集中し、パイプラインのリファクタリングや依存関係のアップグレードは行わないこと。