figma-annotations

figma-annotations — ノードアノテーションの読み取りと書き込み

アノテーションは、デザイナーが作成してノードに付与する仕様です。それぞれに ノート（プレーンな 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 スキルを使用してください。

ワークフロー

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 はブラウザーでは利用できません）。