bdsanxz/figma-access

Figma 访问

您通过一个命令行工具与 Figma 协作。该工具输出 KDL 格式，并将其数据文件保存为 .kdl：每行一个节点，节点的普通字段以 key=value 的形式排在该行上，因此 grep、awk 和 sed 可以直接处理。例外情况包括 spec（打印其自身的每行一个节点的文本大纲）、daemon log（直接打印守护进程的日志行）以及 render、screenshot、image-fills 和 compare（保存图像文件，且其在标准输出上的摘要仍是 KDL 格式）。它有两种接入方式：

• REST（file、node、spec、render、image-fills、api）：使用用户的 token，通过 URL 读取任意文件。无需文件处于打开状态。读取结果会被本地缓存，并在遇到速率限制时自动重试。
• Plugin（exec、screenshot、selection、logs、changes、call）：后台守护进程与 Figma Desktop 中运行的 Desktop Bridge 插件通信。这是修改文件的唯一方式。您的主要工具是 exec，它可以在文件中运行 Figma Plugin API JavaScript 代码。

references/tips.md 中记录了来自实际操作的经验教训，按情境分类。这些是指导而非规则：请阅读您所处情境对应的章节，并根据您的情况进行调整。

规则

• 永远不要显示 token。 不要打印、回显或记录它；使用 figma-access api /v1/me 进行测试。
• 在修改任何内容之前和之后都要查看。 依据图像来判断每一项可见结果，而非依据生成它的代码。
• 读取值，不要猜测；渲染结果说了算。 从文件中获取颜色、尺寸、间距、字体和文本，绝不要通过肉眼从图像中判断。当文件的数据与渲染结果不一致时，渲染结果是用户所看到的。
• 只修改用户要求的内容。 读取操作始终没问题。除非请求明确说明，否则切勿删除或覆盖用户已有的工作。
• 超时并非失败。 Figma 无法停止正在运行的脚本；在重新运行之前，请检查 logs 和文件。

工作流程

1. 设置

1. <skill> 是此 SKILL.md 文件所在的目录。以 bun <skill>/scripts/figma-access.js COMMAND ... 的方式运行工具；本文件将其简写为 figma-access COMMAND ...。它运行在 Bun 而非 Node 上：始终使用 bun 启动，切勿使用 node，并且您编写的任何 JavaScript 或 TypeScript 辅助脚本也应使用 bun 运行。为了缩短命令，可以在每次 shell 调用的开头定义一个 shell 函数（fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...），而不是变量：zsh 不会将变量拆分为单词。对您传递的每个 URL 和节点 ID 加引号：?、& 和 ; 对 shell 有特殊含义。如果缺少 bun，请告知用户从 https://bun.sh 安装并停止执行。
2. 运行一次 figma-access --help，并在首次使用每个命令之前运行 figma-access <command> --help。退出码：0 表示正常，1 表示 Figma 报告了失败，2 表示参数错误，3 表示守护进程、插件或 token 不可用。references/tips.md 中的 “Reading the output” 解释了格式以及如何搜索。
3. 根据请求选择路径，如 references/tips.md 中 “Choosing a path” 所述：如果是 URL 且任务为只读 → 使用 REST；任何对文件的修改 → 使用插件；两者可以同时使用。

2a. 通过 REST 连接

1. 运行 figma-access api /v1/me。如果出现 “no token” 报错：找到用户设置 token 的位置，并在同一个命令中载入它，如 references/tips.md 中 “Token” 所述。仅当在任何地方都没有设置 token 时，才向用户请求一个 token（Figma：设置 > 安全 > 个人访问令牌，文件内容读取权限）。
2. 运行 figma-access file <url> 以查看页面和顶层框架。选择要处理的节点，遵循 references/tips.md 中的 “Finding the right node”。

2b. 通过插件连接

1. 运行 figma-access status。它会在需要时启动守护进程。
   • 如果列出了文件：继续。
   • 如果没有文件：运行 figma-access files，该命令会等待插件。如果它以 3 退出，则运行 figma-access setup 并向用户提供其 steps（用简单明了的语言）：从打印的清单路径导入插件一次，然后在文件中运行 插件 > 开发 > Figma Desktop Bridge，并保持其窗口打开。要求用户在插件运行时告知您，然后再次运行 figma-access files。
2. 如果连接了多个文件：之后的所有命令都需传递 --file <fileKey>。

3. 理解设计

1. 先阅读能够回答问题的最小视图，先看大纲，再仅看您工作的部分的详细信息：
   • 结构：figma-access node <url|key> <id> --outline 2（REST），或 references/plugin-api.md 中的页面大纲配方（插件）；
   • 代码所需的一切，每个可见节点一行：figma-access spec <url|key> <id> -o <file>；对于大型框架，先用 node ... -o <file> 保存一次，然后在所有后续的 spec 命令中传递 --from <file>，如 references/tips.md 中的 “Rate limits and the cache” 所述；
   • 用户所指的 “这个” 或 “选中的”：figma-access selection；
   • 外观：figma-access render <key> <id>（REST，精确尺寸）或 figma-access screenshot <id>（插件），然后打开图像。
2. 阅读 node 的 reports：字体、图像填充以及被修剪的隐藏层数量。阅读 references/tips.md 中的 “Hidden layers” 和 “Reading a design image”。
3. 对于组件、变体、变量和样式，在修改或复制之前先读取它们的真实结构，并重用已有的内容，避免创建重复项。

4. 执行任务

将设计实现为代码。 在编写代码之前，请阅读 references/tips.md 中的 “From design to code”：首次构建后仍存在的差异（图像裁剪、字体、文本偏移、页面宽度）中的大部分都已在那里介绍。将代码放置在用户或其项目指定的位置（他们命名的路径，或项目自身的结构）；_swe/figma-access/ 仅保存工作产物，例如渲染、已保存的节点文件、规格说明、截图和脚本。

1. 以 1 倍比例渲染框架作为参考，如果框架很高，则分段读取。
2. 将框架的 spec 写入文件，使用 --origin 指定页面内容起始的角落，并从该文件中获取所有值。渲染图像，以及被标记为 ICON 或 MASKED 的元素，而不是重新构建它们。根据 spec 打印的方向、间距、内边距和尺寸来构建自动布局框架，而不是根据它们存储的盒子来构建；将没有自动布局的组和框架的子节点放置在其盒子的位置。不要手动或使用生成器将每个节点按存储的盒子进行绝对定位：那样会导致页面复制每个过时的盒子，文本较长时就会错位，并且无法适应窗口。检查每个标记为 LAYOUT DRIFT 的部分与渲染结果是否一致。
3. 列出所有字重下的字体；检查项目中是否有任何非公开字体族的文件，并以一条消息向用户询问仍缺失的字体，以及任何您无法从文件中获取的其他内容。在它们到达之前，或者当您无法询问时，使用替代字体并说明。
4. 去掉设备或浏览器边框，让页面适应窗口：框架的宽度就是其被绘制所针对的屏幕宽度，因此背景和分隔线应跨越整个窗口，而内容列居中，除非用户要求固定宽度。
5. 逐个部分构建，然后使用 figma-access compare <reference.png> <page> --nodes <node file> --wide <px> 将页面与参考进行对比：它会捕获页面，打印框架每个部分中，由导致该差异的偏移量所解释的差异像素数量，每个文本样式和节点偏离的位置和程度，以及缺少的内容，写入差异图像，并检查更宽的窗口。使用 --nodes 时，它会从框架自身的子节点中获取部分，并裁剪出被框架阴影加宽的参考部分。同时查看捕获的图像和差异图像，重复直到每个部分都匹配。当用户要求像素完美或 1:1 的结果，并且您的会话中列出了实现该效果的技能时，请使用该技能，并将这些渲染作为设计图像。

修改文件。 通过插件：

1. 将修改编写为 Plugin API 代码，并使用 figma-access exec 运行，遵循 references/plugin-api.md 中关于 API 强制执行的内容以及放置位置的说明。较长的代码应放入工作文件（例如 _swe/figma-access/ 下），并使用 exec -f 运行。始终 return 您下一步需要的 ID；对于长时间工作，请添加 --timeout 30s 或更长。
2. 对于现有插件例程已涵盖的任务（组件集、lint 和可访问性审计、图像填充、注释、FigJam 和 Slides 辅助函数），使用 figma-access call <METHOD> '<json>'；figma-access methods <filter> 可以列出参数。
3. 每次都要读取输出：如果 ok #false，修复原因并在重试前移除部分工作；如果 resultAnalysis 下出现 warning，检查 ID 和名称；对于脚本自身的跟踪信息，使用 figma-access logs --since 2m。
4. 对您创建或修改的每个节点进行截图（小节点使用 --scale 2），并与请求进行核对。修复并再次截图；经过三轮仍未解决的问题，告知用户还有哪些任务未完成以及原因。

references/tips.md 中的 “Working through the plugin” 涵盖了此处常出错的情况。

5. 报告

告知用户您读取或修改的内容，包括节点名称和 ID，以及您编写的渲染、截图和文件的路径。说明您未完成的任何事项、您做出的每一个假设（替代字体、跳过的隐藏层、去掉的边框），以及未经校验的内容。

故障排除

• “Rate limit exceeded”（429）： CLI 已自动等待并重试。请遵循 references/tips.md 中的 “Rate limits and the cache”，并在下一次大量读取之前等待一分钟。
• 退出码 3，未连接文件： 插件未在该文件中运行，或仍在搜索中（它每隔几秒检查一次）。请用户再次运行它。figma-access daemon log 会实时显示连接情况。
• 另一个工具使用了同一个插件（例如 figma-console-mcp）：两者可以并行工作；figma-access status 会显示此守护进程是否持有该文件。
• 技能更新后行为异常： 再次运行 figma-access setup，要求用户在 Figma 中重新导入清单，然后运行 figma-access daemon restart。
• “Plugin disconnected before it answered”： 用户关闭了插件或文件，或者插件重新加载了。在重复修改之前请检查文件。