annotations-figma 是一个用于在 Figma 节点上读取和写入设计师批注的技能。
用途：批注是设计师编写并附着在节点上的规格说明。每条批注可以携带一条笔记（纯文本标签或富文本 labelMarkdown）、一组被钉住的属性（fills、width、fontSize 等，用于把笔记关联到具体设计属性），以及一个可选分类（interactions、accessibility、dev notes 等）。批注保存在节点上，能经受编辑，并且可撤销（Cmd+Z）。它们适合放置动画时序、缓动曲线、交互行为和无障碍要求这类不属于组件描述的说明。
使用前提与规则：需要先加载官方 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 REST API。
工作流程：
- 获取节点 ID。使用当前选中项或用户提供的节点 ID。批注只适用于支持它的节点类型（frames、components、instances、shapes、text——不包括 pages）。
- 编写带分类的批注时先列出分类。运行分类代码片段，以便传入真实的 categoryId（分类名称按文件而异，无法猜测）。
- 读取：使用 scripts/get-annotations.js，将 INCLUDE_CHILDREN 设为 true 可遍历组件树以获取完整组件文档。
- 写入：使用 scripts/set-annotations.js。选择 MODE：'replace'（默认，覆盖节点上全部批注）或 'append'（保留现有批注）。在 'replace' 模式下传入 ANNOTATIONS = [] 可清除全部批注。
- 校验：重新运行读取脚本，确认批注数量和标签与设置一致。
注意事项：任何文本操作都需要加载字体。批注本身不会渲染你编写的文本，但若工作流还写入文本节点，需先 await figma.loadFontAsync(...)。Figma 在读取时会同时自动填充 label 和 labelMarkdown，但写入时拒绝同时写两者——追加时优先使用 labelMarkdown（若存在），否则用 label，追加脚本已处理这一点。properties 只钉住笔记所针对的属性，并不设置其值，需使用 references/annotation-properties.md 中的确切字符串。这些工具需要 Figma Desktop 应用（浏览器中不提供 Plugin API）。