figma-impl

Figma からの実装を、取得 → 実装 → 検証の3フェーズに固定する。

読み取りと生成を混ぜないことが要点。混ぜると、読めなかった箇所を生成側の推測が静かに埋め、出力を見ても「読んだ値」と「創作した値」が区別できなくなる。区別できないから、修正がランダムウォークになる。

ハードストップ

最初にこれを確認する。

ls .figma-impl/conversion.md .figma-impl/defaults.md 2>/dev/null

どちらか欠けていたら実装に進まない。figma-impl-init を先に実行する必要があることを伝えて止まる。設定が無いまま進めると、その場の推測で埋まって元に戻る。

FIGMA_TOKEN が未設定の場合も同様に止まる。

Phase 1: 取得

**AI が Figma を直接読まない。**スクリプトで機械的に取る。

# Figma で対象レイヤーを選択 → 右クリック → Copy link to selection
# で得られる URL には ?node-id= が含まれる。それをそのまま渡す
node ~/.claude/skills/figma-impl/scripts/fetch-node.js "<FigmaのURL>"

# node-id を明示的に渡すこともできる
node ~/.claude/skills/figma-impl/scripts/fetch-node.js "<FigmaのURL>" 123:456 123:789

**ファイル URL（?node-id= を含まないもの）を渡すとエラーになる。**画面全体を1回で取ろうとせず、末端のコンポーネントを1つずつ指定する運用と対になっている。

出力は .figma-impl/tmp/nodes.json と nodes.md。

**単位を小さく保つ。**画面全体ではなく、末端のコンポーネント1つずつを指定する。ツリーが深いほど、取得漏れが実装側の推測に置き換わる余地が増える。

nodes.md の「欠損（null）の一覧」が、そのまま「AIが創作する場所」のリストになる。ここは埋まっていないのが正しい状態で、埋まっていたらスクリプトのバグ。

REST API は既定値と同じ項目（layoutMode: NONE、padding 0、角丸 0 など）をレスポンスから省く。これは欠損ではないので、公式仕様に default がある項目に限りスクリプトがその値として読む。Auto Layout 無しのフレームでは gap・padding を出力しない（表では —）。

「混在スタイルのテキスト」の節も同じ扱いをする。1つのテキストレイヤー内で部分的にウェイトや色が違う場合、表に出ている値は既定スタイルの代表値でしかない。そのまま単一の値として実装すると、違いが静かに消える。要素を分割するか、該当箇所を個別に確認する。

Dev Mode MCP が使える環境なら、コード生成の足場として併用してよい。ただし確定値は必ず nodes.json を正とする。MCP の生成物には opentypeFlags（palt の有無）が出てこないうえ、Tailwind への丸めが入る。

Phase 2: 実装

**nodes.json と .figma-impl/conversion.md defaults.md だけを見て実装する。**Figma の画面を見に戻らない。

nodes.json で null だった項目には defaults.md の既定値を適用し、適用したものを UNRESOLVED.md に記録する。

**検証で対応付けができるよう、Figma ノードに対応する DOM 要素に data-figma-id 属性を付ける。**これが無いと verify.js が突き合わせられない。

<p data-figma-id="123:456" class="...">…</p>

禁止事項（実装コードに対して）

• **letter-spacing: normal を書かない。**値が無くても 0em と明記する。normal は 0 ではなくフォント固有のカーニング
• **line-height: normal を書かない。**数値で指定する。normal の解決に使う縦メトリクスは Figma とブラウザで採用が違う
• **font-weight にキーワード（bold 等）を使わない。**数値で書く
• **トークンに存在しない生の値を書かない。**必要なら丸めずに報告する
• 表に無い値を推測で埋めない。defaults.md に無ければ Phase 3 のレポートに出す

Phase 3: 検証

**検証したいプロジェクトのルートに playwright が必要。**未導入なら先に入れる。

npm i -D playwright && npx playwright install chromium

node ~/.claude/skills/figma-impl/scripts/verify.js --url <実装したページのURL>

getBoundingClientRect / Range.getClientRects / getComputedStyle で実測し、nodes.json と突き合わせる。出力はズレた行だけ。

閾値は既定 ±1px。**0 にしない。**Figma はテキストをブラウザに描かせておらず（自前レンダラ、ヒンティングなし）、サブピクセル位置の丸めに原理的な差がある。0 にすると永久に緑にならない。

差分が出たら、原因の分類に従って Phase 2 に戻る。

**normal が空になった時点で「数値は届いている」と確定できる。**そこから先に残る差異は、追う必要のない床（ラスタライザ差）だと判断してよい。

ブラウザのコンソールで手早く見るなら scripts/check-normal.js を貼る。

証跡を PR に残す

**「一致しました」を AI の言葉で報告しない。**検証したかどうか自体を人が確かめられないため。差分が無くなったら、PR の最新コミットを push した状態で --pr を付けて実行し、スクリプトに直接投稿させる。

node ~/.claude/skills/figma-impl/scripts/verify.js --url <実装したページのURL> --pr <PR番号>

• レポートは毎回 .figma-impl/evidence/<実行日時>/ に保存される（--pr 無しでも）。--pr を付けると同じ内容を PR にコメントする
• レポートには、検証したコミット SHA、Figma ファイルの version、nodes.json のハッシュ、ブラウザのバージョン、全要素の Figma 値と実測値が載る
• Figma の書き出し画像と実装のスクリーンショットを並べて載せる。画像は証跡専用ブランチ figma-impl-evidence に push し、コミット SHA 固定の URL で参照する。画像は人が見るための参考で、判定には使わない
• 未コミットの変更がある、または手元の HEAD が PR の最新コミットと違う場合は投稿せずに止まる。証跡とコミットを一致させるため
• **--pr には gh（認証済み）と、対象リポジトリへの push 権限が必要。**無い場合は投稿も画像の push もできずに止まる。そのときは --pr を外して実行し、.figma-impl/evidence/ の report.md をそのまま人に渡す
• .figma-impl/tmp/ と .figma-impl/evidence/ は .gitignore に入れる

AI がすることは、投稿されたコメントの URL を伝えることだけ。レポートを要約・転記して PR 本文や会話に「一致」と書かない。

出力形式

UNRESOLVED.md

**質問リストにしない。**Figma を作る人と実装する人は別で、事前に文章で聞いても返ってこない。ビルドを止めないことが前提。出口を3つに分けて書く。

項目ごとの出現回数を集計する。「hover の指定漏れが今月17件」という数字は、Variant 化・Variable 化をデザイナーに依頼するときの材料になる（個人の要望ではなく計測結果として出せる）。

PR 本文

UNRESOLVED.md の内容を**PR 本文に「Figma に指定が無かったのでこうしました」という事後報告の形で出す。**デザイナーは事前の文章には反応しないが、動くものを見ると指摘してくる。この非対称を利用する。

禁止事項

• .figma-impl/ が無い状態で実装に進まない（ハードストップ）
• fetch-node.js を通さずに Figma のスクリーンショットやコピペから値を読み取らない
• **nodes.json の null を埋めるようスクリプトを書き換えない。**null は仕様。例外は公式仕様（figma/rest-api-spec）に default が明記された項目だけで、その場合も根拠をコメントに残す
• 混在スタイルのテキストを、既定スタイルの値で単一に実装しない
• **スクリーンショットのピクセル差分で検証しない。**アンチエイリアスのノイズが支配的で、差分から原因への逆写像が無い
• UNRESOLVED.md をデザイナーへの事前質問リストにしない
• 閾値を 0 にしない
• 検証結果を AI が要約・転記して報告しない。verify.js --pr の投稿だけを証跡とする