figma-version-history

figma-version-history — Figma のバージョンを一覧表示、スナップショット、差分比較

バージョン履歴は Figma の REST API にのみ存在するため、このスキルは個人アクセストークン（PAT）を使って REST API を直接呼び出します。次の 3 つの機能があります。

1. ファイルのバージョン履歴を一覧表示します（ラベル、説明、作成者、タイムスタンプ、バージョン ID）。
2. 指定した version_id 時点のファイル全体、または一部のノードだけをスナップショットします。
3. 2 つのバージョンを比較します。常に軽量なページ構造の差分を表示し、必要に応じて depth=2 でコンポーネントごとの差分も表示します。

セットアップ — ターミナルとトークンが必要です。 このスキルはシェルコマンドを実行するため、Claude Code（Claude Desktop 内の「Code」タブを含む）、Cursor、Codex、Gemini CLI で動作します。シェルがない通常の Claude Desktop や claude.ai のチャットでは動作しません。Figma コネクターの OAuth ログインでは、これらの REST API 呼び出しは認証されません。そのため、独自の Figma 個人アクセストークンを用意する必要があります。Figma で Settings → Security → Personal access tokens に移動し、File content: read（および File versions: read）スコープを指定してトークンを生成してから、シェルで設定します：export FIGMA_TOKEN="figd_…"。スクリプトは実行時に環境変数からトークンを読み込みます。スキルファイルにはトークンを絶対に記載しないでください。

セットアップとスキルの範囲

• すべてのリクエストは、ヘッダー X-Figma-Token: $FIGMA_TOKEN を付けて https://api.figma.com に送信されます。
• エンドポイントのリファレンス：references/endpoints.md。

ファイルキーの取得

ファイルキーは、Figma URL の /design/ または /file/ の後に続くパスセグメントです。

FILE_URL="https://www.figma.com/design/ABC123def456/My-File"
FILE_KEY=$(echo "$FILE_URL" | sed -E 's#.*/(design|file)/([A-Za-z0-9]+).*#\2#')
echo "$FILE_KEY"   # ABC123def456

ワークフロー

1. バージョンを一覧表示して、対象の version_id を確認します。scripts/list-versions.sh を実行します。

   ./scripts/list-versions.sh ABC123def456              # labeled versions only (default)
   ./scripts/list-versions.sh ABC123def456 --autosaves  # include unlabeled auto-saves
   

   バージョンを新しい順に自動でページネーションし、version_id | created_at | author | label の形式で出力します。デフォルトでは、ラベルのない自動保存を除外します。自動保存も含めるには --autosaves を指定します。

2. 1 行の curl コマンドでバージョンをスナップショットします（現在のバージョン／HEAD を対象にする場合は &version= を省略します）。ディスクに保存しておけば、再取得せずに何度でも差分を比較できます。過去のバージョンは変更されません。

   # Whole file at a past version (depth=1 keeps it small for orienting)
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY?version=4096761871&depth=1" \
     > /tmp/v-4096761871.json
   
   # Just specific nodes at that version (much smaller payload)
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=695:313&version=4096761871&depth=2"
   
   # Current / HEAD — omit the version param entirely
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY?depth=1"
   

3. scripts/diff-versions.mjs を使って2 つのバージョンを比較します。両方のスナップショットを取得して、ページ構造の差分を計算します（軽量、2 回の呼び出し）。--components を指定した場合は、深さ 2 でノードごとの差分も表示します（子の追加／削除、名前／説明の変更、COMPONENT_SET の componentPropertyDefinitions の変更、boundVariables の差分）。

   # Page-structure diff only (2 API calls)
   node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to current
   
   # Deep diff of specific component sets (2 calls per node), detailed verbosity
   node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to 4096800000 \
     --components 695:313,420:88 --mode detailed
   

   HEAD と比較する場合は current を指定するか、--to を省略します。--mode には summary（件数のみ）、standard（名前と件数、デフォルト）、detailed（プロパティとバインディングの詳細をすべて表示）を指定できます。

差分で追跡するもの、追跡しないもの

この差分には把握できていない範囲があります。「変更なし」を「何も変更されていない」と解釈しないでください。

• 追跡するもの： ページ構造（ページの追加／削除／名前変更）、対象ノードの子の追加／削除、componentPropertyDefinitions（追加／削除／型／デフォルト値の変更）、名前と説明の変更、変数のバインディング参照。
• 追跡しないもの： キャンバスの別の場所に配置されたコンポーネントのインスタンス（--components で指定したノードのみが対象）、レイアウトの生のプロパティ（hug と fill の違い、バインドされていないパディング／幅／cornerRadius）、バインドされていない塗り／線／エフェクト、変数の値の変更（Figma REST API では公開されません）、スタイルの内容。編集ごとの履歴を調査して、生のプロパティ変更も確認するには、稼働中の Desktop Bridge プラグインにある figma_get_design_changes が補完的なツールです。

注意事項

• Figma のバージョンのページネーションはカーソル方式です。after=<version_id> を指定すると、時間的に古いバージョンが返されます（一覧は新しい順です）。list-versions.sh がこれを処理します。
• 古い version_id は、Figma のプラン別保持ポリシーによって削除されることがあります。スナップショット時の 404 は、キーが間違っているのではなく、通常はバージョンの保持期限が過ぎたことを意味します。有効な ID を取得するには、一覧を再取得してください。
• これらのエンドポイントで 403 が返される場合、PAT に File versions: Read スコープがありません。トークンを再発行してください。