penpot-migrate

penpot-migrate — Figma → Penpot、忠実度を最優先

1. タイトルと仕組み

penpot-migrate は2つのMCP サーバーを橋渡しします。Figma MCP を介してFigmaのデザインを読み込み、Penpot MCP を介してPenpotに書き込みます。すべての変更は execute_code を通じて行い、export_shape で視覚的に検証します。構造の読み取りには penpotUtils.shapeStructure を使用します（ツールの全容： shared/penpot-mcp-tool-reference.md）。FigmaのデータからPenpotに直接書き込むことはありません。まず正規化された **中間表現（IR）**を作成し、次にIRをPenpotの構成要素（ボード、フレックス、トークン、コンポーネント）に変換します。Figma MCPが利用できない場合は、手動で貼り付けたFigmaのエクスポート／JSONを受け取り、それを基に処理します。

2. 最も重要な唯一のルール

**Penpotに書き込む前に必ずIRを作成し、段階的に移行します。**まずトークン、次にコンポーネント、最後に画面を移行し、それぞれを検証します。ファイル全体を一度に移行してはいけません。IRは、FigmaのモデルとPenpotのAPIを切り離す契約です。

3. Penpot MCP ツールリファレンス

全容：shared/penpot-mcp-tool-reference.md。Penpotへの書き込み側：createBoard／addFlexLayout／ addGridLayout、penpot.library.local.tokens.addToken、createComponent／createVariantFromComponents、 忠実度チェック用の export_shape。Figmaからの読み取り側：Figma MCPのデザインコンテキストツール（名称は異なる場合があります。IRが正規化する生データを生成するものとして扱います）。

4. プラグインAPIの要点

注意点の番号は shared/plugin-api-gotchas.md を参照してください。

• Penpotではフレームではなくボードを使用します。Auto Layoutは、ボードのフレックス（dir、間隔、パディング、fill／auto／fixによるサイズ指定）またはグリッドに対応します。
• Figma Variablesは addToken({type,name,value}) を使ってPenpotトークンに変換します。実際の型文字列を使用してください（shared/tokens-schema.json）。FigmaのモードはPenpotのテーマに対応付けます。
• #9 Figmaのコンポーネントセット／バリアントはPenpotのバリアントコンテナーに変換します。penpotUtils.createVariantContainer([{ shape: mainInstance, properties }])（≥ 2.17）を優先してください。低レベルの代替手段は penpot.createVariantFromComponents(mainInstances) です。Board.combineAsVariants(ids) は2.17に記載されていますが未検証のため、使用しないでください。#12にも注意してください。バリアントの変更はファイルを破損させるため、作成してからグループ化する方法を優先し、バリアントコンテナーをその場で編集しないでください。
• #2 トークンの適用は非同期です。1回の呼び出しで適用し、後続の呼び出しで resolvedValue／shape.tokens を確認してください。#4 フレックスは子要素のx／yを上書きします。#6 インスタンス内部を変更する前に切り離してください。
• 不明なシグネチャは、まず penpot_api_info で確認してください。

5. トークンを考慮したブリーフの契約

• コンテキスト — 元のFigmaファイル／スコープ、対象のPenpotファイル、忠実度の期待値。
• 目的 — 単一の目的：「FigmaからPenpotへの忠実度でを移行する」。
• 入力 — Figmaへのアクセス（MCPまたは貼り付けたエクスポート）、命名規則／トークンのマッピングルール。
• 制約 — 階層／レイアウト／バリアントを維持する。Variablesをトークンに対応付ける。グリッドに沿った間隔にする。
• 受け入れ基準 — IRを構築済み。トークンを移行し、値が解決される。コンポーネント／バリアントを再構築済み。画面の見た目が一致する（エクスポートを比較）。忠実度レポートを作成済み。

構造的な忠実度を重視する移行エンジニアとして行動してください。

6. 必須ワークフロー

ビジュアルのセルフレビュー（必須）： ビジュアル成果物を提示するすべての✋チェックポイントの前に、 shared/visual-self-review.md にあるエクスポート → 確認 → 修正のループを実行します。直前に作成した単位をエクスポートし、 チェックリストに照らして自分で画像を確認し、目に見える不具合を修正（最大2回まで）してから、残っている不具合を明示して同じエクスポートを提示します。

Phase 0 — Figma の分析。 ソース（Figma MCP または貼り付けられたデータ）を読み、トークン／コンポーネント／画面を一覧化します（scripts/analyzeFigmaStructure.js、references/01-figma-analysis.md）。✋ チェックポイント：スコープとマッピングルール。

Phase 1 — IR の構築。 IR に正規化します（scripts/buildIR.js、references/02-ir-building.md）。IR はプレーンデータであり、まだ Penpot には書き込みません。✋ チェックポイント：IR の網羅性を確認します。

Phase 2 — トークン。 Variables をトークンに変換します（scripts/migrateTokens.js、references/03-token-migration.md）。penpot-foundations と整合させます。✋ チェックポイント。

Phase 3 — コンポーネント。 コンポーネントとバリアントを再構築します（scripts/migrateComponent.js、references/04-component-migration.md）。✋ チェックポイント。

Phase 4 — レイアウトと画面。 Auto Layout を flex/grid に変換し（references/05-layout-translation.md）、画面を構築します（scripts/migrateScreen.js、references/06-screen-migration.md）。✋ 画面ごとのチェックポイント（export_shape）。

Phase 5 — 再現性を検証。 scripts/validateFidelity.js（references/07-validation.md）で、構造、トークン、ビジュアル比較を検証します。結果を報告します。（問題への対応にはreferences/08-error-recovery.mdを参照します。）

7. 重要なルール

1. Penpot に書き込む前に IR を構築します。
2. トークン → コンポーネント → 画面の順に移行し、それぞれを検証します。
3. Auto Layout は flex/grid に変換します。Auto Layout で構成されたものに絶対配置を使用しないでください。
4. Variables は実際の型文字列を持つトークンに変換し、モードはテーマに変換します。
5. Figma MCP がない場合は、適切に縮退します（貼り付けられたデータを受け入れます）。
6. 再現性の不足は正直に報告します。実際にそうでない場合に 1:1 と主張しないでください。

8. ドメインアーキテクチャ

IR（プレーンな JSON）によって2つのツールを分離します：

{ tokens:[{type,name,value,mode?}],
  components:[{name, variantProps?, layout, children:[...]}],
  screens:[{name, size, layout, children:[...]}] }

各 IR ノードには、Penpot で同等のものを構築するために必要な情報が含まれます（レイアウト = flex/grid 仕様、子要素はコンポーネントまたはプリミティブを参照します）。IR を読み込み、Penpot に書き込みます。

9. モードとポリシー

デフォルトはレビューです。コンポーネント／バリアントの再構成と切り離しは自動で行いません（shared/modes-and-policies.md）。

10. 状態管理

RUN_ID の下に台帳を保持します：phase、ir（またはそのポインター）、migrated:{tokens,components,screens}、gaps:[...]。IR は再開可能な成果物です。切り詰めが発生した後は、IR を再読み込みします。

11. ユーザー確認ポイント

フェーズ終了後	成果物	確認事項
0	一覧 + マッピングルール	スコープ／マッピングを承認しますか？
1	IR の網羅性	IR を承認しますか？
2	移行済みトークン（tokenOverview）	トークンを承認しますか？
3	コンポーネント／バリアント	コンポーネントを承認しますか？
4	画面の export_shape	画面を承認しますか？

12. 命名規則

shared/naming-conventions.md：Figma の名前を Penpot の規則に合わせてマッピングします（コンポーネントは PascalCase、バリアントは Property=Value、レイヤーはセマンティックな名前、トークンはドット表記）。

13. 正当化を防ぐための表

言い訳	誤りである理由	対策（停止）
「IR を省略して、Figma から直接 Penpot に書き込む。」	2つのモデルが密結合し、脆弱で情報が失われます。	まず IR を構築し、そこから変換します。
「ピクセルを合わせるためにすべてを絶対配置にする。」	Auto Layout のレスポンシブ性が失われます。	Auto Layout を flex/grid にマッピングし、Figma で絶対配置されていた箇所に限って絶対配置を使います。
「Variables をハードコード値として再作成する。」	トークンシステムが失われます。	Variables をトークンに、モードをテーマに移行します。
「ファイル全体を一度に移行する。」	一括処理では再現性が損なわれ、監査もできません。	トークン → コンポーネント → 画面の順に段階的に進め、それぞれを検証します。
「Figma MCP が接続されていないので、デザインを推測する。」	推測すると、実際にはないデザインを作り出してしまいます。	エクスポートデータ／JSON の貼り付けを依頼し、実データを基に作業します。
「完全な 1:1 だと主張する。」	Figma の機能には、正確にマッピングできないものがあります。	再現性の不足は正直に報告します。

14. ヘルパーコードスニペット

// Translate an IR layout node to a Penpot flex Board
function buildFromIR(node, parent){
  const b = penpot.createBoard(); b.name = node.name;
  if (node.layout && node.layout.type === "flex"){
    const f = b.addFlexLayout();
    f.dir = node.layout.dir || "column";
    f.rowGap = node.layout.rowGap || 0; f.columnGap = node.layout.columnGap || 0;
  }
  (parent || penpot.currentPage.root).appendChild(b);
  return b;
}
return { ok: true };

15. 参考リソース

• penpot_api_info('Board')、penpot_api_info('VariantContainer')、penpot_api_info('TokenSet')。
• Figma MCP のデザインコンテキストツール（名称はバージョンによって異なります）— Figma MCP 自体の概要から確認してください。

16. 関連ファイル

references/: 01-figma-analysis.md、02-ir-building.md、03-token-migration.md、04-component-migration.md、05-layout-translation.md、06-screen-migration.md、07-validation.md、08-error-recovery.md。 scripts/: analyzeFigmaStructure.js、buildIR.js、migrateTokens.js、migrateComponent.js、migrateScreen.js、validateFidelity.js。

Doctrine のパス。 shared/… と policies/… は、ネイティブインストールではこのバンドル内を参照します（インストーラーによって同梱されます）。Claude Code プラグインとしてインストールした場合は、プラグインのルートにあり、このファイルから 2 つ上のディレクトリにある ${CLAUDE_PLUGIN_ROOT}/shared/… を参照します。