技能使用指南

figma-analyzer（Figma分析器）Skill 是什么？如何一键提取设计资产？

Figma分析器Skill 基于 Figma REST API，一键将框架与组件导出为 PNG、SVG 等图像，并提取节点元数据、设计令牌与文件结构，输出标准 JSON，可与多模态分析技能联动完成 UI 研究。本文详解安装配置、命令用法、竞品对比与真实场景体验，帮你把设计稿变成可编程资产，立即上手试试。

Figma分析器Skillfigma-analyzer
8 个章节 约 18 分钟阅读 AI 智能生成

Figma分析器Skill：用 Figma REST API 把设计稿变成可编程的设计资产与令牌

  • 一句话定位：通过 Figma REST API，把 Figma 文件中的框架、组件、元数据和设计令牌批量导出为图片与结构化 JSON，让 AI 与工程流程都能直接“读懂”设计稿。
  • 三大核心能力：资产导出（PNG、JPG、SVG、PDF，支持 1x/2x/3x/4x 缩放与批量节点）、元数据提取（文件结构、页面层次、节点属性、组件样式、版本历史）、设计令牌提取（颜色、排版、效果、栅格布局）。
  • 典型的获取方式：配置好 FIGMA_ACCESS_TOKEN 环境变量并安装 requests、python-dotenv 两个依赖后，用一条 figma_export.py 命令即可完成导出。
  • 可与视觉分析技能联动：导出图像后可直接交给多模态分析技能做 UI 研究，形成“导出—分析—产出规范”的闭环。
  • 适合谁用：需要还原设计稿的前端工程师、维护设计系统的设计工程师、做 UI 研究的 AI 应用开发者，以及需要批量归档设计资产的团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
技能中文名 Figma分析器Skill
技能英文名 figma-analyzer
技能 ID 11841
许可证 MIT
允许使用的工具 Bash、Read、Write

它解决的问题：Figma 里的设计稿本质上是以“画布和节点”形式视觉呈现的，工程侧和 AI 侧都无法直接读取。设计师交付的往往是一张截图，或者需要人工逐个查看的标注页面。前端工程师为了拿到准确的颜色、字号、间距和阴影参数，只能反复查看或手工复制；AI 模型做 UI 研究时，也缺少统一格式的设计输入。

Figma分析器Skill 的作用，就是把“视觉设计”转换成“机器可读的资产”：一方面把指定的框架或组件渲染成图片，另一方面把节点结构、组件定义、颜色、排版和效果样式输出为标准 JSON。这样，设计稿就变成了可以被脚本、AI 代理和工程流水线继续处理的数据。

一键安装与启用的整体思路

第 1 步，准备 Figma 访问令牌。按照技能说明，获取方式是：

  1. 前往 Figma 设置中的「账户」页面；
  2. 滚动到「个人访问令牌」区域；
  3. 生成一个具有读取权限的新令牌。

第 2 步，把令牌配置到环境中。技能会按以下顺序依次查找 FIGMA_ACCESS_TOKEN，只要命中任一位置即可生效：

  1. 进程环境：export FIGMA_ACCESS_TOKEN="your-token"
  2. 项目根目录的 .env
  3. .claude/.env
  4. .claude/skills/.env
  5. .claude/skills/figma-analyzer/.env

第 3 步，安装 Python 依赖：

pip install requests python-dotenv

第 4 步，把技能放入项目的技能目录（从上面的查找顺序可以看出，技能目录约定为 .claude/skills/figma-analyzer），具体的安装命令与入口以官方说明为准。

第 5 步，验证是否生效。最简单的方式是查看脚本帮助信息，确认脚本可执行：

python scripts/figma_export.py --help

也可以直接对一个测试文件执行元数据抓取（--metadata-only）。若能正常输出 JSON，说明令牌与依赖都已配置正确。

这样做的价值在于：整个过程是一次配置、长期复用的。相对而言，每次交付都要重新手工抄写标注并逐个导出切图，之后的常规导出只需复制一行命令。

2. 该技能的主要功能和特点

（1）资产导出：把任意框架和组件变成图片

  • 支持导出为 PNG、JPG、SVG、PDF 四种格式，覆盖位图交付、矢量二次编辑与文档归档三类需求。
  • 支持 1x、2x、3x、4x 缩放比例，便于生成高清分析图或 Retina 素材。
  • 支持通过 --node-ids 以逗号分隔的方式批量导出多个节点，一次命令导出整套页面。
  • 导出的图片可直接写入本地文件系统，输出路径由 --output 指定。

（2）元数据提取：还原设计的结构信息

  • 输出文件结构、页面层次结构，能看清一份文件中有哪些页面、页面下有哪些框架。
  • 输出节点属性：名称、类型、绝对包围盒（x、y、宽度、高度）、约束与子节点关系。
  • 输出组件与样式定义，以及文件版本历史。
  • 支持 --metadata-only 模式，只获取元数据、不产生图片，适合轻量探查大文件。

（3）设计令牌提取：让设计规范变成可落地变量

  • 颜色样式与调色板，包含色值与设计侧命名（如“蓝色 500”）。
  • 排版样式：字体族、字号、字重、行高。
  • 效果样式：阴影类型、偏移、模糊半径、颜色。
  • 栅格与布局样式，以及间距阶梯（xs、sm、md、lg、xl 等）。

（4）兼容 AI 工作流

  • 导出图像后可交给多模态分析技能（ai-multimodal）进行视觉理解，例如“分析布局并提取组件规范”。
  • 技能说明中明确它与 ui-researcher 代理、/ui-research 命令协同，构成完整的 UI 研究工作流。

（5）工程健壮性设计

  • 按 Figma 官方速率限制处理：免费层级每分钟 300 个请求，付费层级根据计划有更高上限，并采用指数退避重试。
  • 提供完整的错误码对照（400、403、404、429、500）与对应的排查建议。
  • 大量 API 端点封装在单一 CLI 之后，使用者不需要自己拼接请求。

和普通做法的差别：手动导出只能得到图片，得不到结构；自己写脚本能拿到结构，但要自己处理分页、限流、退避和节点解析。这个技能把“导出图像、抓元数据、抽令牌”三件事合并到一条命令里，并把结果统一成可被下游程序消费的 JSON。

3. 如何使用该技能？

步骤 1：解析 Figma URL

Figma 链接包含文件密钥（file_key）和可选的节点 ID（node-id）：

https://www.figma.com/file/{file_key}/{file_name}?node-id={node_id}
https://www.figma.com/design/{file_key}/{file_name}?node-id={node_id}

例如整份文件是 https://www.figma.com/file/ABC123/MyDesign，某个具体框架则是 https://www.figma.com/file/ABC123/MyDesign?node-id=1-234。

步骤 2：把设计导出为图像

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design?node-id=1-234" \
  --output docs/research/ui/design.png \
  --scale 2

输出说明：在 docs/research/ui/ 下生成 2 倍分辨率的 PNG，可用于评审、视觉分析或作为参考图。

步骤 3：只抓文件元数据

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --metadata-only \
  --output docs/research/ui/figma-metadata.json

输出为结构化 JSON，包含 file_key、name、last_modified、thumbnail_url，以及以节点 ID 为键的 nodes 对象，节点内包含名称、类型、绝对包围盒和子节点。

步骤 4：提取设计令牌

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --extract-tokens \
  --output docs/research/ui/design-tokens.json

输出包含 colors、typography、effects、spacing 四类结构，例如颜色项为 {"primary": {"value": "#3B82F6", "name": "蓝色 500"}}，排版项包含 fontFamily、fontSize、fontWeight、lineHeight。这些结构可以直接映射为 CSS 自定义属性。

步骤 5：批量导出多个框架

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --node-ids "1-234,1-235,1-236" \
  --output docs/research/ui/frames/ \
  --scale 2

步骤 6：与视觉分析技能串联

python .claude/skills/figma-analyzer/scripts/figma_export.py \
  --url "$FIGMA_URL" \
  --output docs/research/ui/design.png \
  --scale 2

python .claude/skills/ai-multimodal/scripts/gemini_batch_process.py \
  --files docs/research/ui/design.png \
  --task analyze \
  --prompt "分析布局并提取组件规范" \
  --output docs/research/ui/analysis.md \
  --model gemini-2.5-flash

步骤 7：常用参数速查

参数 作用
--url Figma 文件或框架 URL（必填）
--output 图像或数据的输出路径
--scale 导出缩放比例（1、2、3、4）
--format 导出格式（png、jpg、svg、pdf）
--node-ids 逗号分隔的节点 ID，用于批量导出
--metadata-only 仅获取元数据，不导出图像
--extract-tokens 提取设计令牌
--verbose 输出详细日志

错误排查参考：400 一般是 URL 或节点 ID 格式有误；403 是令牌无效或没有该文件权限；404 是文件密钥或节点不存在；429 触发了速率限制，需要退避后重试；500 为服务端错误，可用指数退避重试。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
figma-analyzer（本技能） 面向 AI 与工程流程的 Figma 资产提取技能 图像导出、元数据抓取、设计令牌提取、批量节点处理、可与多模态分析联动 需要一个 Figma 个人访问令牌，并安装 requests、python-dotenv；以命令行方式使用 UI 研究、设计系统审计、设计稿归档、AI 视觉分析前置流程 优势是命令行化、输出标准 JSON、内置限流处理；不足是需要基础命令行能力，且依赖 Figma API 权限
直接调用 Figma REST API 自写脚本 完全自定义的底层方案 可调用全部端点，灵活度最高 门槛最高：需自行处理鉴权、分页、退避、节点递归与格式转换 有特殊字段需求、需要深度定制的团队 优势是自由度最大；不足是开发与维护成本高，重复实现已有能力
Figma 客户端手动导出 + 人工整理 传统交付方式 手工导出切图与标注，人工抄写颜色字号 几乎无技术门槛，但纯人力 体量很小的单页交付 优势是零学习成本；不足是不可批量、易出错、无法产出结构化的设计令牌
第三方设计交付/代码生成平台 商业化设计交付工具 标注查看、切图下载、部分代码生成能力 通常需要另行注册与配置，具体能力与费用以官方说明为准 团队协作交付、设计到代码的初步生成 优势是界面友好、协作功能完整；不足是数据不在本地、难以嵌入自定义 AI 分析流程

选型建议：如果你希望设计资产能直接进入脚本与 AI 流程，本技能的“本地 CLI + 标准 JSON”组合最省事；如果只是偶尔看一两个页面，手动导出反而更快；如果需要极特殊的字段组合，才值得自己写 API 脚本。

5. 该技能的典型应用场景与实际体验情况

场景一：前端工程师高保真还原设计稿

痛点：拿到设计稿后，间距、圆角、阴影值靠肉眼估算，还原度反复被退回。

使用方式：先用 --extract-tokens 导出设计令牌，把 spacing、colors、typography 映射成 CSS 变量；再用 --node-ids 批量导出各区块 2 倍图作为对照。实际体验上，令牌 JSON 的字段命名与前端变量体系一一对应，替换成本很低；需要注意的是，令牌的完整度取决于设计侧是否把样式真正“发布”为样式，未发布的零散样式不会出现在结果中。

场景二：AI/多模态 UI 研究

痛点：想让模型分析竞品或自有产品界面，但模型只能看到截图，缺少结构信息。

使用方式：先用本技能导出框架图，再交给多模态分析技能，以“分析布局并提取组件规范”为提示词生成分析文档。实际体验上，两段命令串起来就能跑通，适合批量处理多个页面；注意导出时用 2 倍缩放能明显改善文字识别效果，透明背景的元素建议用 PNG 而非 JPG。

场景三：设计系统维护者做令牌审计与同步

痛点：设计侧改了主色或字号阶梯，工程侧的主题变量没同步，导致界面不一致。

使用方式：定期对设计库文件执行令牌提取，与仓库中的主题文件做差异比对。实际体验上，把“核对设计规范”从人工检查变成一次命令加一次 diff，效率提升明显；建议把令牌文件纳入版本管理，便于追溯变更历史。注意遵守速率限制，不要对同一文件高频轮询。

场景四：设计资产归档与文档化

痛点：项目结项时，历史版本的设计稿散落在 Figma 里，无人整理。

使用方式：用 --metadata-only 抓取整份文件的结构与版本历史，用批量导出把关键框架一次性落盘到 docs/ 目录。实际体验上，对大文件先抓元数据、看清页面结构后再决定导出哪些节点，比直接整份导出更省时间，也更容易避开限流。

整体上手难度：中等偏低。会执行命令行、会配置环境变量就能用；真正的学习成本在于理解设计令牌与工程变量之间的映射关系。

6. 该技能能为用户带来的价值

效率提升：把“导出切图、抄写标注、整理颜色字号”这类重复劳动压缩成几条命令。原本需要逐页复制参数的交付流程，现在可以一次批量导出多个节点，再用一份 JSON 覆盖整份文件的设计规范。

门槛降低：不需要了解 Figma REST API 的鉴权方式、分页规则和速率限制，也不需要自己写递归遍历节点树的代码。技能已经把端点调用封装好，并内置了指数退避重试和错误码对照，非 Figma 平台方向的开发者也能顺利上手。

可量化的收益方向：节省设计还原时的沟通轮次、减少因数值不一致导致的返工、把设计规范的同步从“人工核对”变成“可 diff 的文件比对”。另外，元数据与令牌都是文本类产物，可以纳入版本管理，形成可追溯的设计变更记录。

长期价值：它让设计资产从面向人的视觉呈现，转变为面向程序的机器可读输入。一旦设计稿能稳定产出结构化数据，后续的自动化代码生成、视觉回归测试、AI 辅助 UI 评审都有了统一的数据入口，而不必每次都从零搭建。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要准备什么？

A：核心是三件事：一是在 Figma 设置的个人访问令牌页面生成一个读取权限令牌，并配置为 FIGMA_ACCESS_TOKEN 环境变量（可放在进程环境或约定的 .env 文件中）；二是执行 pip install requests python-dotenv 安装依赖；三是把技能放到 .claude/skills/figma-analyzer 目录。之后用 python scripts/figma_export.py --help 验证即可。具体安装命令以官方说明为准。

Q2：使用这个技能要收费吗？

A：技能本身以 MIT 许可证开源，使用时不需要付费。需要留意的是 Figma API 的调用频率限制：免费层级为每分钟 300 个请求，付费层级根据计划有更高上限，因此实际可用吞吐与你的 Figma 账户计划相关，具体以官方说明为准。

Q3：它和直接在 Figma 里手动导出切图有什么区别？

A：手动导出只能得到图片，无法得到文件结构、组件定义和设计令牌；本技能在导出图像之外，还能输出结构化 JSON，并且支持批量节点导出与命令行集成，能被脚本和 AI 流程直接消费。如果只是需要一两张图，手动导出确实更快；但只要涉及规范同步或自动化流程，技能的优势就体现出来了。

Q4：没有设计背景的开发者能用吗？

A：可以。命令行参数只有八个左右，常用的是 --url、--output、--scale 和三个模式开关（--metadata-only、--extract-tokens、--node-ids）。真正的难点不在操作，而在于如何把导出的设计令牌映射到项目里的 CSS 变量或主题配置上，这部分需要结合自身项目结构来判断。

Q5：导出时报 403 或 429 怎么办？

A：403 通常表示访问令牌无效或当前账号对该文件没有读取权限，需要检查令牌是否具备读取权限、以及是否属于正确的 Figma 账号；429 表示触发了速率限制，应当等待后重试，技能已内置指数退避策略，同时建议减少高频轮询、优先用节点 ID 过滤缩小请求范围、并对元数据做本地缓存。