figma-generate-component-doc

figma-generate-component-doc — 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 ...）。与 figma-export-tokens 的分工相同。如果无法运行 Node，就无法生成文档 — 请如实说明，不要手动编写。
• Markdown 章节布局和 cleanVariantName 规则 → references/doc-template.md。转换器已实现该文件中的所有规则；应将其视为规范，而不是手动组装文档的清单。
• 将注释作为独立规范进行读写 → 使用 figma-annotations 技能。
• 导出整个令牌系统（而非仅一个组件的令牌）→ 使用 figma-export-tokens。

工作流

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

说明

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