figma-generate-component-doc

figma-generate-component-doc — Figma コンポーネント → Markdown ドキュメント

1 つのコンポーネントまたはコンポーネントセットについて、概要、構造ツリー、デザイントークン、バリアント／状態のマトリクス、タイポグラフィ、アクセシビリティ、コンテンツガイドライン、および（任意で）デザインとコードの整合性、YAML フロントマターを含む完全なドキュメントページを作成します。このスキルは use_figma を介してファイルから構造化データを収集し、その後、決定論的な Node コンバーター（scripts/generate-doc.mjs）が Markdown を出力します。同じ収集済み JSON からは常に同一の Markdown が生成されます。文章をもとにドキュメントを手作業で作成しないでください。

スキルの範囲

• use_figma のルール — まず公式の figma-use スキルを読み込んでください。これは Figma Plugin API の完全なリファレンスです。このスクリプトが前提とする重要事項：トップレベルの await + return を使ったプレーンな JS（IIFE や figma.closePlugin() は使わない。console.log の内容は返されません）、各スクリプトの先頭で入力値を const として直接記述すること、色は 0～1 の範囲で指定すること、テキスト操作の前にフォントを読み込むこと、await figma.getNodeByIdAsync(...) を使うこと、そしてアトミックエラー（スクリプトが失敗すると変更は一切適用されません。エラーを読み、修正して再試行してください）。
• 収集スクリプトはどこでも実行できます（use_figma）。コンバーターは Node で、ターミナルから実行します（node scripts/generate-doc.mjs ...）。figma-export-tokens と同じ役割分担です。Node を実行できない場合、ドキュメントは作成できません。手作業で作成するのではなく、その旨を伝えてください。
• Markdown セクションの構成と cleanVariantName のルール → references/doc-template.md。コンバーターにはこのファイルのすべてのルールが実装されています。手作業で組み立てる際のチェックリストではなく、仕様として扱ってください。
• 注釈を個別の仕様として読み書きする場合 → figma-annotations スキルを使ってください。
• トークンシステム全体をエクスポートする場合（1 つのコンポーネントのトークンだけではない場合）→ figma-export-tokens を使ってください。

ワークフロー

1. 対象を特定します。 現在の選択範囲、またはユーザーが指定した URL／ID から、コンポーネントまたはコンポーネントセットのノード ID を取得します。バリアントを含むコンポーネントセットを使うと、最も充実したドキュメントを作成できます。収集スクリプトで NODE_ID を設定してください。また、ファイル URL（figma: リンク／フロントマター用）も控えてください。
2. データを収集して JSON に保存します。 scripts/collect-component-data.js を use_figma から実行します（skillNames: "figma-generate-component-doc"）。構造ツリー、バリアントごとの色（バインドされたトークン ID と名前を含む）、タイポグラフィ（フォントファミリー、数値のウェイトと名前、サイズ、行の高さ、文字間隔）、スペーシングトークン、コンポーネントのプロパティ定義（バリアント／ブール値／テキストプロパティ）、説明、注釈（カテゴリ名を含む）が返されます。返された JSON はファイルに保存してください（例：collected.json）。
3. Markdown を生成します（決定論的）。 ターミナルで Node コンバーターを実行します。

   node scripts/generate-doc.mjs collected.json [--code-info codeInfo.json] [--out docs/components/Button.md] [--frontmatter] [--file-url <figma-url>]
   

   ソースジェネレーターのセクション構成をそのまま適用します。概要（説明から抽出した「使用する場面」および「使用しない場面」を含む）、コンポーネント構造、バリアント（マトリクス＋アイコンのマッピング＋設定可能なプロパティ）、トークン仕様（色とスペーシングの表）、タイポグラフィ、コンテンツガイドライン、アクセシビリティ、デザイン注釈、さらに --code-info を指定した場合は実装、デザインとコードの整合性、変更履歴が含まれます。 cleanVariantName は自動的に適用されます（Type=Image, Size=12 → Image / 12）。同じ入力なら、同一の出力になります。
4. コードとの整合性を追加する場合は任意です。 実装／整合性／[View Source] および [Storybook] リンクを追加するには、コンポーネントのソースを読み、codeInfo.json（props、importStatement、sourceFiles、baseComponent、changelog など）を作成してから、--code-info codeInfo.json を指定します。
5. フロントマターの追加は任意です。 --frontmatter を指定すると、YAML フロントマター（title、status、version、tags、figma URL、lastUpdated）が先頭に追加されます。
6. 確認して納品します。 出力された Markdown を読み、問題がないか確認してから、書き込むか返します。パスと、1 行の概要（バリアント数、トークン数）を報告してください。

補足

• フォントの読み込み： Figma にテキストを書き込むステップ（たとえば、ドキュメントをキャンバスに書き戻す処理）を追加する場合は、最初に await figma.loadFontAsync(...) を実行してください。純粋なドキュメント生成では読み取りのみを行います。
• collect スクリプトでは、深い階層でペイロードが大きくなりすぎないよう MAX_DEPTH を使用しています。構造が途中で切れている場合にのみ、値を増やしてください。
• トークン名は boundVariables から取得します。バインドされた変数がない色や間隔は、トークンテーブルでは — と表示されます（トークンに置き換えるハードコード値です）。
• コンバーターは依存関係なしで動作します（Node 18 以降、ESM）。JSON が見つからないか、不正な形式の場合は、明確なメッセージを表示してゼロ以外のステータスで終了します。
• これらの collect ツールには Figma Desktop アプリが必要です（Plugin API はブラウザーでは利用できません）。