generate-component-doc-figma

generate-component-doc-figma — Figma 组件 → Markdown 文档

为单个组件或组件集生成完整的文档页面：概述、结构树、设计令牌、变体／状态矩阵、排版、无障碍、内容指南，以及（可选）设计与代码的一致性和 YAML frontmatter。本技能通过 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 技能。
• 导出整个令牌系统（而非仅导出单个组件的令牌）→ 使用 export-tokens-figma。

工作流

1. 确定目标。 从当前选区或用户提供的 URL／ID 获取组件或组件集节点 ID。组件集（包含变体）可生成最丰富的文档。在收集脚本中设置 NODE_ID。同时记下文件 URL（用于 figma: 链接／frontmatter）。
2. 收集数据 → 保存 JSON。 通过 use_figma 运行 scripts/collect-component-data.js（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。 传入 --frontmatter，在文档开头添加 YAML frontmatter（标题、状态、版本、标签、Figma URL、更新时间）。
6. 检查并交付。 阅读生成的 Markdown，进行合理性检查，然后写入文件／返回内容。报告文件路径和一句摘要（变体数量、令牌数量）。

说明

• 字体加载： 如果添加了向 Figma 写入文本的步骤（例如将文档盖印回画布），请先执行 await figma.loadFontAsync(...)。纯文档生成只会读取内容。
• 收集脚本使用 MAX_DEPTH 来控制深层树结构的负载大小；只有在结构信息看起来被截断时才提高此值。
• 令牌名称来自 boundVariables；没有绑定变量的颜色或间距在令牌表中会显示为 —（表示需要用令牌替换的硬编码值）。
• 此转换器不依赖任何依赖项（Node 18+，ESM）。如果 JSON 缺失或格式错误，它会以非零状态码退出，并显示清晰的提示。
• 这些收集工具需要 Figma Desktop 应用（浏览器中无法使用 Plugin API）。