figma-annotations

figma-annotations — 读取和写入节点注释

注释是由设计师撰写、附加到节点上的规范。每条注释可以包含备注（纯文本 label 或富文本 labelMarkdown）、一组固定属性（fills、width、fontSize，等等），用于将 备注关联到特定设计属性；还可以包含可选的类别（交互、无障碍、开发备注，等等）。注释保存在节点上，编辑后仍会保留，并且可以撤销（Cmd+Z）。动画时长、缓动曲线、交互行为和无障碍要求等不适合写在组件描述中的内容，都适合记录在这里。

技能边界

• use_figma 规则——先加载官方 figma-use 技能；其中包含完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用纯 JS，并在顶层使用 await + return（不使用 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 设为 true，即可遍历组件树，获取完整的组件文档。
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）。