generate-component-doc-figma

generate-component-doc-figma — 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 ...）。export-tokens-figma と同じ分担です。Node を実行できない場合、ドキュメントは生成できません。手作業で作成せず、その旨を伝えてください。
• Markdown のセクション構成と cleanVariantName のルール → references/doc-template.md。コンバーターはそのファイルのルールをすべて実装しています。手作業で組み立てる際のチェックリストではなく、仕様として扱ってください。
• アノテーションを単独の仕様として読み書きする場合 → annotations-figma スキルを使用してください。
• トークンシステム全体をエクスポートする場合（1 つのコンポーネントのトークンだけではない場合）→ export-tokens-figma を使用してください。

ワークフロー

1. 対象を特定します。 現在の選択範囲、またはユーザーが指定した URL／ID から、コンポーネントまたはコンポーネントセットのノード ID を取得します。バリアントを含むコンポーネントセットを使うと、最も充実したドキュメントを生成できます。収集スクリプトで NODE_ID を設定します。また、ファイル URL（figma: リンク／フロントマター用）も記録します。
2. データを収集し、JSON を保存します。 scripts/collect-component-data.js を use_figma 経由で実行します（skillNames: "generate-component-doc-figma"）。構造ツリー、バリアントごとのカラー（紐付けられたトークン 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 を読み、内容に問題がないか確認してから、書き出すか返します。パスと簡潔な要約（バリアント数、トークン数）を報告します。

補足

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