understand-figma

/understand-figma

Figma ファイルを分析し、既存のダッシュボードにインタラクティブなデザインナレッジグラフを生成します。

前提条件

• FIGMA_TOKEN 環境変数 — Figma の個人用アクセストークン（https://www.figma.com/settings で作成してください）。設定されていない場合は、処理を中止して次のようにユーザーに伝えてください。

  まず Figma トークンを設定してください。figma.com/settings で作成してから、export FIGMA_TOKEN=<token> を実行してください。

• Node ≥ 22、pnpm ≥ 10。

セキュリティ： トークンは環境変数からのみ読み取られ、X-Figma-Token リクエストヘッダーでのみ送信されます。グラフ、meta.json、ログ、中間ファイルには絶対に書き込まないでください。このスキルは api.figma.com に外部リクエストを送信します。/understand とは異なり、完全なオフライン動作ではありません。この点をユーザーに一度伝えてください。

フェーズ 0 — 事前確認

1. $ARGUMENTS を解析し、Figma URL またはファイルキー単体（フラグではないトークン）と、任意の --language <lang> を取得します。
2. PROJECT_ROOT を現在の作業ディレクトリに解決します。データディレクトリ $UA_DIR を解決し、以下のすべての読み取りと書き込みで再利用してください。UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)" — 既存の場合は従来の .understand-anything/、それ以外の場合は新しい .ua/ を使います。各フェーズは新しいシェルで実行されることがあるため、$PROJECT_ROOT と同様に $UA_DIR を引き継いでください。後続のコマンドブロックで必要になった場合は、同じ行を使って再解決します。
3. PLUGIN_ROOT を解決し、/understand のフェーズ 0.1.5 と同じ方法でコアがビルド済みであることを確認します。packages/core/dist/figma/index.js が存在しない場合は、次を実行します。

   cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
   

4. mkdir -p $UA_DIR/intermediate を実行します。

フェーズ 1 — 取得と解析（決定的処理）

バンドル済みのスキャンスクリプトを実行します（<SKILL_DIR> はこのスキルのディレクトリです）。

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

スクリプトは $UA_DIR/intermediate/scan-manifest.json に書き込み、ノード数を出力します。件数をユーザーに伝えてください。終了コードが 0 以外の場合は、標準エラー出力を伝えて処理を中止します。

スキャンで UP_TO_DATE が出力された場合は、「この Figma ファイルのバージョンでは、デザイングラフはすでに最新です」と報告して処理を中止します。完全に再構築するには、環境で UNDERSTAND_FIGMA_FORCE=1 を設定して再実行してください。

フェーズ 2 — 分析（LLM による補強）

1. scan-manifest.json を読み取ります。ノードを、可能な場合はページごとにまとめて、約 15 件ずつのバッチに分けます。
2. 各バッチについて、design-analyzer エージェント定義（agents/design-analyzer.md）を使ってサブエージェントを起動します。次の情報を渡してください。
   • ノードのバッチ（id、type、name、figmaMeta、子ノード名、トークン使用量）
   • 既存ノード ID の全リスト
   • $INTERMEDIATE_DIR = $UA_DIR/intermediate
   • 出力ファイル名に使用するバッチ番号 エージェントは analysis-batch-<N>.json を書き込みます。 --language が指定されている場合は、$LANGUAGE_DIRECTIVE を追加します（/understand の指示文を再利用してください）。
3. 最大 5 バッチを同時に実行します。バッチが失敗した場合は警告を記録して続行します。マニフェストは十分な基盤になります。

フェーズ 3 — マージ

node <SKILL_DIR>/figma-merge.mjs "$PROJECT_ROOT"

scan-manifest.json と analysis-batch-*.json を結合し、mergeDesignGraph を実行します（検証し、kind:"design" を再付与）。そして knowledge-graph.json と meta.json を書き込みます。出力された統計情報と、auto-corrected 以外の問題をユーザーに伝えてください。

フェーズ 4 — 保存と起動

1. scan-manifest.json 以外の中間ファイルを削除します。

   INTER="$UA_DIR/intermediate"
   find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-manifest.json' -exec rm -rf {} +
   

2. プロジェクト名、ノードタイプ別の件数、エッジタイプ別の件数、レイヤー数、ツアーのステップ数、および $UA_DIR/knowledge-graph.json のパスを含む概要を報告します。
3. /understand-dashboard スキルを呼び出して、ダッシュボードを自動起動します。