annotations-figma

annotations-figma — ノードの注釈を読み取り・書き込み

注釈は、デザイナーが作成してノードに付ける仕様です。それぞれに メモ（プレーンな label またはリッチテキストの labelMarkdown）、メモを特定のデザイン属性に関連付ける ピン留めされたプロパティ （fills、width、fontSize、…）、および任意の カテゴリ（インタラクション、アクセシビリティ、 開発メモ、…）を含められます。注釈はノードに保存され、編集後も保持され、取り消し可能です（Cmd+Z）。 コンポーネントの説明に含めるべきではないアニメーションのタイミング、イージングカーブ、インタラクションの動作、 アクセシビリティ要件を記載するのに適しています。

スキルの範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。これは Figma Plugin API の完全なリファレンスです。これらのスクリプトが前提とする要点：トップレベルの await と return を使ったプレーンな JS（IIFE や figma.closePlugin() は使用しない。console.log の内容は返されません）、各スクリプトの先頭で入力を const としてインライン化する、カラー値は 0～1 の範囲にする、テキスト操作の前にフォントを読み込む、await figma.getNodeByIdAsync(...) を使用する、および アトミックエラー（スクリプトが失敗すると何も適用されません。エラーを読み取り、修正して再試行してください）。
• 有効なプロパティ型と形式 → references/annotation-properties.md。
• コメント（ノード仕様ではなく、ファイル単位のディスカッションスレッド）は対象外です。代わりに Figma の comments REST API を使用してください。

ワークフロー

1. ノード ID を取得します。 現在の選択項目、またはユーザーから指定されたノード ID を使用します。注釈を付けられるのは、対応する型のノード（フレーム、コンポーネント、インスタンス、図形、テキストなど。ページは対象外）のみです。
2. カテゴリを指定する注釈を書く場合は、まずカテゴリを一覧表示します。 カテゴリ用のスニペットを実行し、実在する categoryId を渡せるようにします（カテゴリ名はファイルごとに異なり、推測できません）。スクリプトを参照してください。
3. scripts/get-annotations.js を使って 読み取ります。コンポーネント全体のドキュメントを取得するには、INCLUDE_CHILDREN を設定してコンポーネントツリーをたどります。
4. scripts/set-annotations.js を使って 書き込みます。MODE を選択します： 'replace'（デフォルト。ノード上のすべての注釈を上書きします）または 'append'（既存の注釈を保持します）。 'replace' とともに ANNOTATIONS = [] を渡すと、すべての注釈を消去できます。
5. 検証します。 読み取りスクリプトを再実行し、注釈の数とラベルが設定した内容と一致することを確認します。

注意事項

• テキスト操作では、どの操作でもフォントの読み込みが必要です。 作成したテキストは注釈自体には表示されませんが、ワークフローでテキストノードも書き込む場合は、先に await figma.loadFontAsync(...) を実行してください（規約を参照）。
• Figma は読み取り時に label と labelMarkdown の両方を自動入力しますが、両方を指定して書き込むことは拒否されます。追記する場合は、labelMarkdown があればそれを、なければ label を優先してください。追記スクリプトではすでにこのように処理しています。
• properties は、メモがどの属性についてのものかを指定するだけで、その値は設定しません。references/annotation-properties.md に記載されている正確な文字列を使用してください。
• これらのツールを使うには、Figma Desktop アプリが必要です（Plugin API はブラウザーでは利用できません）。