最近我把 Codex 开源的 Figma Skill 翻了个底朝天。说实话见过太多挂羊头卖狗肉的AI 辅助设计转代码方案但这次这个开源项目给我的感觉不太一样——它不是简单教 Agent 截个图再猜代码而是把 Figma 的设计数据、图层结构、样式约束变成了一组可控制、可验证、可回退的技能。这个方向非常值得研究。你想想Figma 这样的设计工具本身是一个巨大的信息孤岛设计稿里每一帧、每个组件、每套样式规则数据全在里面但 Agent 默认根本看不懂。Codex 的开源 Figma Skill 做的事情就是在这个孤岛和代码 Agent 之间搭一条结构化的通道让 Agent 不只是看设计稿而是懂设计稿。这篇文章我就从原理层面把它拆开讲清楚顺便把我跑通时踩过的坑、调试过的细节一并分享出来给准备入手的同学做个参考。1. 先把概念盘明白Codex、Figma、Skill 到底各是什么角色1.1 Codex 不是一个 IDE 插件那么简单很多人一听到 Codex第一反应是OpenAI 出的一个 IDE 里的 AI 编程助手。这个理解不算错但太小了。Codex 的底层是一个能自主规划、执行、验证任务的编码智能体Coding Agent它不止能在你写代码时做补全还能替你完成一整条任务链路读取项目结构、分析需求、修改文件、跑测试、看报错日志然后根据反馈继续调整。这里的关键词是自主。如果只是在一个 IDE 里做代码补全那能力边界很清楚光标在哪它就管哪。但 Codex 这种智能体式工具边界是我给你的目标和它能触达的环境。也就是说Codex 能发挥多大作用很大程度上取决于它能访问到多少上下文。它能看到的越多决策就越准产出的代码就越贴合真实需求。这就引出一个矛盾编码场景的上下文好解决读代码库文件就行但设计场景的上下文呢一个 PSD 或者 Figma 文件Codex 默认是打不开的更别提理解里面那些图层约束、间距变量、自动布局规则。所以要让 Codex 能真正按设计稿开发必须先解决设计稿怎么被 Agent 读取的问题。1.2 Figma设计师的主战场开发者的黑箱Figma 到今天基本已经是 UI/UX 设计的标准工具尤其在 Web 和 App 产品设计里团队协作几乎绕不开它。它的优势很明显多人实时协作、组件化设计、自动布局、Design Token 体系都做得很成熟。但问题也出在这里。对设计师来说Figma 文件是清清楚楚的图层该分组的都分好了样式该统一的也统一了。可对开发者来说一个 Figma 文件往往像个黑箱——你得打开它一帧一帧看一个图层一个图层拖才能还原出设计稿的意图。更麻烦的是传统设计转代码的方式是依赖人工读图开发者看标注、量间距、查色值然后手写 CSS 或者小程序代码。这个过程的效率瓶颈在于信息搬运大量时间花在把视觉信息翻译成代码的机械操作上而不是真正的逻辑思考上。1.3 Skill 在 Codex 里的定位给 Agent 装上专用器官聊完前两个概念Skill 就很好理解了。在 Codex 的体系里Skill 不是一套固定的提示词模板而是一个定义了输入方式、动作集合、输出约束、回退策略的可执行能力模块。你可以把它理解成给 Agent 装上一个专用器官有了这个器官Agent 才具备处理某类特殊任务的能力。比如你给它装一个数学建模 Skill它就学会了从问题描述到建模、求解、验证的一套完整操作方式给它装一个科研 Skill它就能按文献检索、实验设计、数据处理的方法论工作。而这次我们要聊的 Figma Skill 就是专为设计稿理解和设计稿转代码准备的一个器官。这个器官的核心价值在于它没有让 Agent 去猜设计稿而是让 Agent 通过一套明确的操作协议去读取设计稿结构。这不是语义上的小差别是根本上的设计哲学差异猜意味着幻觉率很高读意味着每一步都有据可查。2. 设计思路拆解为什么要做一个Figma Skill而不是塞一套插件2.1 设计稿到代码最痛的不是画图是翻译我在之前团队里带过两次设计转开发的完整流程一次是外包团队做一次是内部研发做。两次最耗时的环节都非常一致不是画界面而是翻译设计稿。设计师交付的稿子里包含了大量隐含信息哪些间距是统一的哪些颜色是 Token哪些组件是可复用的哪些交互状态需要单独处理。这些信息在 Figma 里都有结构化表达但开发者往往需要肉眼去识别、靠经验去推理。举个很常见的例子设计稿里两个卡片之间看起来都是 16px 的间距但如果你去翻 Figma 的自动布局设置会发现一个是固定 16px另一个是min gap 12px 自适应。如果靠肉眼看你会写出一模一样的代码但靠 Skill 读取结构数据Agent 能发现这两者的约束不同进而生成不同的布局代码。这种细节才是真正拉开 AI 生成质量差距的地方。2.2 Skill 的核心原则最小输入、稳定输出、失败可回退我看完这个开源 Skill 的代码结构之后最大的感受是它非常克制。它没有试图一步到位用一条 prompt 让 Agent 自己看着办而是把整个任务拆成了三层输入层、动作层、校验层。输入层解决Agent 怎么告诉 Skill 它想看什么默认支持用文件链接、文件 ID、页面名或者选区 ID 指定目标。动作层解决Skill 能对 Figma 做什么读取画布结构、获取样式信息、导出资源图片、写入标注动作集合是可扩展的。校验层解决Agent 怎么确认拿到的信息是对的拿到结构数据后会检查关键节点是否齐全、样式字段是否缺失缺了就自动重试或者返回明确错误信息。这个三层结构看着简单实际上把所有边界情况都兜住了。Agent 不会因为拿到一个空的图层列表就开始胡编代码而是会收到一条类似未找到指定 Frame请检查页面名或选区 ID的反馈然后自动调整自己的下一步动作。2.3 和 MCP、Figma Plugin 的区别很多同学会问这个 Skill 和市面上已有的方式有啥区别我整理了一张对比表给你看更直观对比维度Figma SkillFigma MCP Server传统 Figma Plugin运行主体Codex Agent 内部调度独立 MCP 服务通过协议对接Figma 客户端内运行主要能力结构化读图、分析、辅助出码提供 API 让 Agent 调用由设计师手动触发操作上下文理解强结合任务上下文中按接口返回数据弱只处理当前选中对象扩展方式改 Skill 定义文件改 MCP server 端逻辑改插件代码适合场景Agent 自主完成设计研发闭环多人共用一套数据服务设计师手动提效MCP 和 Plugin 不是不好而是它们解决的问题边界不一样。MCP 偏接口暴露适合把 Figma 数据开放给外部系统Plugin 偏人工辅助适合设计师在画布上操作时一键批量处理。而 Skill 更偏能力编排它站在 Agent 的角度把理解设计稿这个复杂任务拆成了一系列 Agent 能执行、能校验、能纠错的步骤。这也就是我为什么觉得这个开源项目值得研究它不是在跟 MCP 抢赛道而是在补位。Agent 需要的不只是数据接口更是一套怎么用这些数据的方法论。3. 开箱即用的原理拆解Figma Skill 到底是怎么工作的3.1 一次完整调用链路走一遍我直接用一个实际场景串一遍假设我的项目里需要让 Codex 照着 Figma 里一版登录页设计稿实现前端页面。Codex 接到了这个任务后不会直接去猜。它会先调用 Figma Skill 里定义好的 read_frame 动作入参是design_url或file_key frame_name。Skill 收到指令后会通过 Figma REST API 拉取该 Frame 的节点数据包括子节点层级、组件实例、样式 token、布局约束等。拿到的原始 JSON 数据是很大、很杂的。Skill 不会把所有数据原样甩给 Codex而是会对它做一层提炼把与前端实现相关的字段保留宽高、间距、颜色、字体、圆角、填充、边框、自动布局方向等把无关信息丢掉坐标值、协作记录、版本号等。这一步很关键它大幅降低了 Codex 的上下文开销也让后续生成的代码更聚焦。提炼完的数据会整理成结构化的文本摘要返回给 Codex。Codex 再基于这份摘要结合项目里的现有代码框架生成前端页面代码。如果生成的代码里需要用到某个资源图片比如背景图Skill 还提供了 export_image 动作可以直接把指定节点的图片导出为文件供 Codex 引用。整条链路走完你会发现每一步都有明确的输入输出契约没有任何一步是靠猜的。这就是它能稳定工作的原因。3.2 Skill 的 manifest 与命令映射机制我没有把整个项目代码贴出来但它的核心结构短小精悍几乎都是围绕一个skill.yaml来组织的。我理解的大致结构是这样name: figma-reader version: 0.1.0 description: 帮助 Codex 读取和理解 Figma 设计稿结构 actions: - name: read_frame description: 读取指定画板的结构和样式数据 params: file_key: type: string required: true description: Figma 文件标识 frame_name: type: string required: false description: 页面中 Frame 的名称 steps: - call: figma_api.get_file_nodes - transform: filter_design_tokens - result: structured_frame_summary它的执行逻辑也很直观Codex 在收到读图类的指令时会在它的 Skill 池里检索发现figma-reader有对应的read_frame动作于是读取这个动作定义的步骤列表逐步执行。每一步都有一个明确的功能调接口、过滤数据、结构化输出。这样做的好处是几乎不需要复杂的代码逻辑整个 Skill 的本质是一堆指令序列 数据转换规则。Agent 本身拥有推理能力Skill 只需要告诉它怎么做以及按什么格式输出剩下的判断和生成交给 Agent 自己完成。这也是 Skill 机制比传统硬编码脚本灵活很多的地方。3.3 三种动作类型读、写、校验深入看它定义的动作集合基本上可以归成三类读动作read_xxx获取画布结构、样式、组件信息、导出的资源图片。这是最高频的一类也是整个 Skill 的基石。写动作write_xxx向 Figma 写入标注、修改图层命名、生成导出版本。这类动作常用于 Agent 把代码实现状态反馈回设计稿方便设计师 review。校验动作validate_xxx检查当前设计稿是否符合既定的规范比如是否有缺失的样式变量、是否用了不合理的间距值。这类动作让 Codex 在做自动化的 UI 审查时有据可依。这三类动作组合在一起覆盖了 Agent 在设计研发场景里大部分需要的能力。读动作让 Agent 理解设计写动作让 Agent 反馈实现校验动作让 Agent 把关质量。三个维度闭环了Agent 才能不只是生成代码而是真正参与设计研发协作。3.4 为什么用结构化描述而非直接截图我见过不少团队做过类似的事直接把设计稿截图扔给多模态模型让它照着图写代码。这种方式在简单的页面上效果还行但一遇到复杂设计就崩原因有两点一是截图丢失了结构信息。肉眼能看出两个元素对齐了、间距是 16px但模型从像素图上很难准确推断出这些数值更别说判断对齐方式是基于 flex 还是 absolute positioning。二是截图不可校验。如果模型生成的结果不对你找不到中间环节是哪里出了问题——是看错了图还是理解错了约束而用结构化描述的方式每一步都有明确的 JSON 数据流出了问题能找到具体是哪个节点、哪个字段被误解了。所以这个开源 Skill 坚持用 Figma API 拉取结构数据再加工而不是投机取巧只做图像识别背后是有清晰的技术判断的稳定性和可调试性比短期看起来的聪明更重要。4. 实操从零跑通一个最小 Figma Skill4.1 准备阶段需要做什么实操部分我默认你已经装好了 Codex 的基础环境。装好的标志是你在命令行能直接执行codex命令并且能正常发起一个简单的问答任务。接下来需要准备两样东西一个是 Figma 的 Access Token另一个是 Skill 的配置文件。Figma Token 在 Figma 个人设置页面里生成把它配成环境变量名字建议叫FIGMA_ACCESS_TOKEN。这个 Token 是 Skill 调 Figma API 的凭证注意别提交到公开仓库里。Skill 配置文件一般放在 Codex 约定的 skills 目录下。如果你用的是 OpenAI Codex CLI 那一套通常是~/.codex/skills/或者项目目录下的.codex/skills/具体看你的版本约定。放好之后Codex 启动时会自动扫描并注册该 Skill。注意不同版本的 Codex 对 skill 目录的扫描规则可能不一样。我建议你放好后先用codex skill list之类的命令验证一下确认注册成功再继续别直接跑大任务否则定位问题会很痛苦。4.2 最小可用的 Skill 文件示例我给你一个最精简的示例这个文件能实现一个功能让 Codex 读取指定 Figma 文件的画布结构并以树形文本输出。name: figma-mini version: 0.1.0 description: 读取 Figma 页面结构 actions: - name: dump_page_structure description: 打印指定页面的节点层级 params: file_key: type: string required: true page_name: type: string required: false steps: - name: fetch_document call: figma_api.get_document map: file_key: params.file_key - name: filter_page call: builtin.filter_nodes map: condition: node.type CANVAS node.name params.page_name - name: format_tree call: builtin.to_tree_text这个文件本身不是一个可以直接运行的完整程序它更像是一份给 Codex 参考的操作说明。Codex 读到之后会按照steps里定义的顺序调用对应的内置函数或者外部接口最后把结果返回给用户。如果你只是自己测试不一定要把这个文件做得很完整。可以先在项目里准备一个 Figma 测试文件创建一个简单的画板放几个基础组件然后让 Codex 用 figma-mini 这个 skill 看看这个页面的结构观察它是否能成功调通接口并返回结构树。4.3 调试验证的具体流程我自己的调试流程一般分三步你照着做能省很多时间首先用一个非常简单的 Figma 文件做冒烟测试。不要一上来就用复杂的页面容易把问题复杂化。建一个新的 Figma 文件只画一个按钮、一个文本框固定 16px 间距然后让 Codex 读取并描述它。如果这一步通了基础链路就没问题。其次检查返回的 JSON 是否完整。Codex 返回的结果不只会有文字描述通常还会包含一些调试信息比如接口返回的状态码、节点数量、字段缺失提示。重点看有没有READ_FAILED之类的错误标记有的话多半是 Token 权限不足或者 file_key 拼错了。最后做一次设计转代码的完整试验。让 Codex 基于读取到的结构生成一个 React 或者 HTML/CSS 版本。看它生成的代码里间距、颜色、字号是否和设计稿一致。这一步验证的不是 Skill 能不能跑通而是数据加工的质量够不够高。我实测过一个比较典型的案例让 Codex 复刻一个卡片列表组件设计稿里每个卡片是 16px 圆角、浅灰描边、标题字号 16pt 加粗。第一次生成时Codex 写出了 16px 圆角但描边用了默认色而非设计稿的浅灰把结构摘要里描边颜色缺失这个字段补全后第二次输出就完全正确了。这件事说明Skill 的输出数据质量直接决定了 Codex 的还原精度调试时一定要舍得在数据加工这一层下功夫。5. 常见问题与排查速查5.1 几个高频报错和对应的处理思路我在跑这个 Skill 的过程中以及翻阅社区反馈时整理了几个高频出现的问题列成表格方便你排查现象大概率原因排查与解决调用 Skill 后 Codex 说找不到这个 Skill配置文件路径不对或 Codex 缓存未刷新检查 skill 文件是否放在约定目录重启 Codex 或执行 skill 重载命令返回403 forbiddenFigma Token 权限不足或 Token 过期重新生成 Token确认勾选了 File content 读取权限返回404 not foundfile_key 或 node_id 拼写错误到 Figma 文件 URL 里复制正确的 file_keynode_id 需 URL 编码结构摘要里大量字段为 null设计稿里的样式没有走 Token 体系或节点类型不支持检查 Figma 中该节点是否有自动布局确认读取的是 Frame 而非 Group生成的代码颜色偏差明显Skill 返回的颜色格式是 RGB 但代码里需要 Hex在 Skill 的 transform 里加一步颜色格式转换本地代理服务端口冲突本地开发环境中有其他服务占用了 Codex 依赖的端口检查环境变量中是否配置了代理改端口后重启服务上面这几种问题绝大多数都不是 Codex 本身的问题而是环境配置或数据准备的问题。先把这些基础项排除干净再怀疑 Skill 逻辑本身。5.2 两个最容易让人放弃的坑第一个坑是 Token 权限没给够。Figma 的 Token 权限看起来都是读文件但实际上细分了好几个层级。如果你只勾了File viewingAPI 是拿不到完整节点数据的必须确认开了File content那一层。这个坑藏得很深因为有些接口调用会成功只是返回的数据是空的导致你在后面疯狂排查为什么 Codex 读不到内容。第二个坑是自动布局数据的歧义。我遇到过好几次Figma 里明明元素之间留了 24px 的间距但 Skill 返回的摘要里写的是gap: 0。后来发现这个间距是由外层容器的 padding 实现的而不是子元素之间的 gap。这种语义差异如果不处理Agent 生成的代码必然跟设计稿有出入。解决方法是让 Skill 在返回数据时把 Container 的padding和子元素的margin都显式带上不要只保留一个参数。使用心得设计稿转代码这件事真正的难点从来不是认识屏幕上的形状而是理解设计系统里暗含的约束关系。Skill 的价值在于把这些约束显性化、可达化。6. 我对开源和生态扩展的几点看法6.1 开源让这个 Skill 的使用边界变大了我个人认为这个项目选择开源是个非常正确的决定。原因在于设计转代码是一个非常依赖团队实践的场景——每个团队的设计规范不同前端技术栈不同甚至设计师写稿的习惯都不同。一个闭源的、封死的 Skill 只能覆盖通用场景很难深入解决具体团队的痛点。开源之后团队可以基于自己的需求去改动作定义比如加一个读取 Design Token 的专用动作或者加一个输出 Tailwind 配置的转换逻辑。只要遵循原来的结构定义扩展开销很低。我甚至见过有团队把 Skill 的动作从读取设计稿扩展到了自动生成设计走查报告纯靠新增几个校验类动作就实现了。另外开源的另一个好处是社区能快速找到并修复问题。Figma API 偶尔更新字段结构闭源工具等官方适配可能要几周开源项目社区往往几天内就有人提交修复。对依赖这个 Skill 做日常开发的团队来说这个修复速度很关键。6.2 后续可以往哪些方向扩展如果你打算把这个 Skill 用到实际项目中我建议重点关注三个扩展方向接入组件库映射在 Skill 的数据加工层把 Figma 里的组件实例映射到前端项目已有的组件库比如 Button、Input、Card。这样 Codex 生成的代码会直接用它自己的组件而不是从零写一套。增加响应式标注意图让 Skill 在读取 Frame 时额外分析自动布局在不同断点下的行为生成响应式布局建议减少开发时自己猜断点的成本。和设计规范校验打通把 Skill 的 validate 动作接到你团队的设计规范文档上。Codex 生成完代码后可以反向调用校验动作确认实现稿和设计规范是否有出入形成闭环。这三个方向都不需要推翻现有 Skill 的结构只是在动作层和数据加工层做增量扩展。这也是它架构设计得好带来的红利——核心骨架不用动能力边界可以不断往外长。最后说几句我自己的感受我在实际把 Codex 的 Figma Skill 跑通之后最大的感受是这条路走对了。它不是让 AI 替代设计师也不是让 AI 替代程序员而是把设计意图到代码实现这条路上最消耗人力的信息搬运环节自动化了。程序员不再需要盯着标注一个一个量间距设计师也不用反复解释稿子里某个布局为什么这样设定因为 Skill 已经把这一切转成了双方都能理解的结构化数据。虽然目前这个开源 Skill 还有不少可以优化的细节比如对超大文件的性能处理、对复杂组件嵌套的解析能力但它已经证明了一个重要的事情设计稿和代码之间的距离是可以被技术大幅缩短的。如果你也在做设计转代码相关的工具或者流程我强烈建议你把它下载下来拆一遍很多设计思路看完会很有启发。别只当一个用户用当成一个样例去研究收获会大很多。
