annotations-figma

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

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

技能边界

• use_figma 规则——先加载官方的 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的基本要求：使用顶层 await + return 的纯 JS（不要使用 IIFE 或 figma.closePlugin()；console.log 不会作为返回值返回），在每个脚本顶部以内联 const 声明输入，颜色范围为 0–1，进行任何文本操作前先加载字体，使用 await figma.getNodeByIdAsync(...)，并遵循原子错误原则（脚本执行失败时不会应用任何更改——读取错误、修正后重试）。
• 有效的属性类型和结构 → references/annotation-properties.md。
• 评论（文件级讨论串，而非节点规格说明）不在此范围内——请改用 Figma 的 comments REST API。

工作流

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）。