Figma 与 Dev Mode 设计交付、代码映射与团队治理手册
开发照着标注做，为什么上线后仍然对不上
一个结算页已经进入联调。设计师在按钮实例上把左右内边距改成了 20，开发从 Dev Mode 复制到的却仍是组件库旧值 16；图标看起来同名，实际一个来自主组件，一个已经被 detach；浅色模式验收通过，深色模式引用的变量却没有发布。最后，设计稿、组件库、代码仓库都声称自己是“最新”，团队却无法证明开发当时读到的是哪个 Frame、哪个组件版本和哪组变量值。
问题不在于少抄了四个像素，而在于团队把持续变化的设计文件误当成静态标注。Figma 的画布对象、库资产、变量、版本历史和 Dev Mode 状态分别保存不同事实。开发交付必须固定对象身份、状态和版本证据，再把设计对象映射到代码对象。普通文件链接默认指向文件的最新版本，不能把它当成不可变快照；还要保存文件、节点、命名版本和导出物之间的对应关系。
先认清文件里的对象身份
Figma Design 文件位于 team 或 organization 下的 project 中，也可能暂存在个人 Drafts。文件内部再由 Page、Section、Frame 和 Layer 组织内容。它们不是可以互换的视觉分组：
Page 隔离较大的工作流或产品区域，适合区分探索稿、交付稿和归档区。Section 给一组 Frame 增加语义和 Dev Mode 状态，适合表示一个功能切片。Frame 同时承担布局容器、原型节点和开发检查对象，是交付链接常见落点。
Component 是可复用定义；Instance 是对主组件的引用；detach 后只剩普通图层，不再接收主组件更新。Variable collection 保存变量集合及其 mode；变量可以被组件属性、颜色、尺寸或文本等对象引用。
新人最容易把“长得一样”理解成“身份相同”。选中按钮后，先在右侧面板确认它是 Instance 还是普通 Frame，再定位 main component、variant 和 component property。若无法跳到主组件，或属性面板里没有实例关系，应先判断是否被 detach，而不是继续按截图猜实现。
变量也不能只看当前渲染值。color/text/primary 在 Light mode 可能解析为一个颜色，在 Dark mode 解析为另一个颜色；开发应记录变量名、collection、mode 和解析值，而不是只复制最终十六进制值。变量本身可以在各 plan 使用，但每个 collection 可创建的 mode 数量随 plan 变化；要跨文件使用变量，还需要在支持 library 的团队中发布并由消费文件接受更新。变量、集合与模式说明给出了 Color、Number、String、Boolean 四种变量类型以及 mode 的组织方式。
浏览器与桌面应用怎么选
Figma 以浏览器为主要运行入口，打开 https://www.figma.com/ 登录后即可进入文件浏览器；Linux 和 ChromeOS 通常使用浏览器。浏览器需要 WebGL，企业浏览器策略若禁用硬件加速、拦截第三方存储或强制严格隐私模式，常见现象是画布空白、缩放卡顿、字体或图片加载失败。遇到这类问题，先在受支持浏览器的新配置文件中复现，再检查扩展、代理、WebGL 与显卡驱动。系统与浏览器要求列出了当前最低浏览器、操作系统和 WebGL 条件。
Windows 与 macOS 可以从 Figma 桌面应用指南进入官方安装包。桌面应用与浏览器核心能力接近，但它能直接访问本地字体，也是开发和发布 Plugin、Widget 的必要入口。受管开发机要由 IT 决定安装目录、自动更新和本地字体策略；Figma Desktop 安装的本地后台服务会在 loopback 地址上工作，安全软件若拦截 localhost 通信，可能出现字体不可用或链接无法拉起桌面应用。
完成安装后不要用“能登录”作为验证。创建一个测试文件 Checkout Handoff Lab，建立 Sandbox Page，再创建 Button/Primary Frame，并在浏览器与桌面应用之间分别打开。两端应看到相同对象和评论；桌面端应能使用允许的本地字体。若浏览器正常而桌面端空白，证据重点是桌面应用调试日志、代理和 WebGL；若只有字体不同，检查字体是否安装、是否被企业字体策略阻止，而不是重做组件。
测试结束后把实验文件移到团队约定的 Sandbox project 或 Trash。不要把它留在个人 Drafts 充当团队模板，因为 Drafts 的所有权、可见性和离职迁移都不适合作为长期依赖。
建立一个可检查的最小组件
在测试文件中创建两个变量 collection：Primitive 与 Semantic。Primitive 保存原始值，Semantic 通过 alias 指向原始值。这样代码关心 color/action/primary，而不是关心某个暂时的蓝色值。
Primitive
color/blue/600 = #2563EB
color/blue/500 = #3B82F6
Semantic
color/action/primary = Primitive.color/blue/600 (Light)
color/action/primary = Primitive.color/blue/500 (Dark)
space/control/x = 16
radius/control = 6然后创建 Button component set，至少包含 variant=primary|secondary、state=default|disabled 两个属性；把填充、圆角和水平间距绑定到语义变量。拖出一个 Instance，分别切换 variant、state 和 mode。正确结果不是“按钮变色了”这么简单，而是：
Instance 仍能回到同一个 main component。切换 mode 时绑定的变量名不变，解析值变化。修改 main component 后，Instance 显示可接受的库更新，而不是静默失联。
Dev Mode 选中实例时能看到组件身份、属性、变量和布局值。
反向实验也要做一次：复制 Instance 后执行 detach，再修改 main component。detach 对象不会收到更新，Inspect 里也失去 main component 关系。这就是线上常见的“视觉还像，治理已经断链”。修复方式通常不是手工把差异抄回去，而是重新放置正式 Instance、迁移必要 override，并删除 detached 副本。
用 Dev Mode 读取证据，而不是复制答案
在付费团队中，Full 或 Dev seat 才能进入 Dev Mode，快捷键为 Shift+D；Starter 文件不能把 Dev Mode 当作可用前提。Collab 和 View seat 仍可在 Design Mode 做基础 inspection，例如查看属性、复制代码和导出资产，但没有 Dev Mode 的高级检查和变更比较能力。具体能力还受文件的 can view / can edit 以及复制、分享和导出限制影响；遇到入口缺失时，先核对 seat、文件权限和团队 plan。Dev Mode 管理说明和检查设计指南分别说明了席位和检查权限。
第一次交付可以按下面的顺序完成：
设计师在准备交付的 Section 或 Frame 上设置 Ready for dev，补充行为说明与异常状态。开发从交付链接进入对应 Frame，而不是从文件首页自行搜索同名页面。选中根 Frame，确认更新时间、尺寸、布局和 prototype 入口；再逐层检查组件实例与变量。
在 Inspect 中切换 CSS、iOS 或 Android 语言与单位，确认单位缩放符合项目约定。对已修改对象使用 Compare changes，确认此次差异，而不是重新肉眼扫描整个页面。把当前文件链接、Frame 的 node ID、命名版本、工单 ID 和代码提交写入同一条交付记录；文件链接只负责定位当前文件，不承担不可变快照语义。
Dev Mode 使用指南说明 Inspect、Compare changes、Ready for dev、资产下载和状态通知的行为；检查设计指南还明确了没有 Dev Mode 时可用的基础检查。自动生成的 CSS、SwiftUI 或 Android 片段是翻译提示，不是可直接合并的生产代码：它不知道项目的组件封装、响应式断点、可访问性约束、浏览器兼容和业务状态模型。复制后至少要经过 lint、类型检查、视觉回归和组件 API 评审。
正向实验：固定一次可复核的交付快照
版本历史保存的是整个文件的检查点，不是独立的 Frame 文件。为包含 Button/Primary 的文件保存一个短命名版本，例如 PAY-142-button-handoff，在描述里写清组件库版本、变量 mode、Frame 名称和验收状态；再把该 Frame 的节点链接和 node ID 记录到工单。标题过长会被截断，不能把完整证据只放在标题里。将 Frame 标记为 Ready for dev，然后用另一个测试账号通过当前文件链接打开它。
测试账号应能完成四项核对：定位同一个 Frame；看见 main component 身份；在属性或 Dev Mode 变量详情中看见 color/action/primary、collection、mode 和解析值；在文件允许复制/导出的前提下导出测试图标。只有 Full/Dev seat 才验证 Dev Mode 专属能力；View/Collab 账号应明确验证基础 inspection 的结果。随后将下面的证据对象放入虚构工单，字段名也可以直接转成团队模板：
handoff:
ticket: PAY-142
figma_file: checkout-lab
frame: checkout-confirmation
frame_node_id: "123:456"
file_link: https://www.figma.com/design/<file-key>/<file-name>?node-id=123-456
named_version: PAY-142-button-handoff
status: ready-for-dev
component_set: Button
component_variant: primary/default
variable_mode: Light
code_component: packages/ui/src/button.tsx
acceptance:
- keyboard-focus-visible
- dark-mode-visual-regression
- icon-export-hash-recorded预期证据是访问者看到的组件名、变量名和 mode 与记录一致，工单中的 node ID 能把人带到同一对象。命名版本只作为文件检查点证据，不表示当前文件链接会停留在该版本；需要把某一历史版本交给开发时，不能假定查看者能打开版本链接，应该复制该版本为独立交付文件，或交付导出物与哈希。若访问者只能看到画面而无法 Inspect，检查其 seat 与文件权限；若能 Inspect 但变量显示原始值，检查图层是否真正绑定变量；若链接打开后落在别的对象，重新复制选中 Frame 的节点链接，并核对 file key、node ID 和当前文件权限。
实验结束后撤销测试账号、删除测试导出物并将测试文件移入 Trash。权限撤销后用无痕窗口重新验证：若同时关闭 public link，预期是登录或拒绝访问；若保留 public link，则应明确记录它仍可被访问以及只能查看还是还能复制/导出。仍可访问通常意味着文件继承了 project/team 权限，或启用了 public link，不能仅凭 URL 判断权限已回收。
反向实验：制造一次标注漂移
先记录 Ready for dev Frame 中按钮的 space/control/x=16，然后让设计者在 main component 把变量改为 20，但故意不发布 library 更新，也不重新设置交付状态。开发仍打开同一个当前文件和 node 链接并比较结果；不要用“旧文件链接”假定它会停留在旧快照。
可能出现三种证据：
当前文件里的本地主组件已经变化，实例随之变化，但其他消费文件没有更新提示，说明变化未发布到 library。library 已发布，但消费文件尚未接受更新，实例仍保留旧版本。实例曾被 detach，既没有更新提示，也无法比较 main component。
这三个现象不能用同一句“Figma 缓存了”解释。先看实例身份，再看 library 发布记录，最后看消费文件的待更新状态。修复后重新创建命名版本、更新 Ready for dev 状态，并在代码评审中把旧快照标为 superseded。只有开发重新读取变量、视觉回归变绿，漂移才算关闭。
资产导出要把格式、倍率和来源一起交付
Figma 可为图层设置 PNG、JPG、SVG、PDF 导出；Dev Mode 还会识别图标并提供资产下载，也能下载部分媒体节点或原始图片。具体格式与入口可查 Dev Mode 使用指南。选择格式时要由运行环境决定：照片通常进入有损栅格格式，透明 UI 位图使用 PNG，图标优先 SVG，但 SVG 必须经过安全与优化门禁。
导出前固定三类字段：源 node、导出设置、消费路径。不要把 logo-final-final.svg 当来源证据。可以在仓库维护不含访问令牌的清单：
{
"asset": "checkout-lock",
"figmaNode": "123:456",
"format": "svg",
"destination": "apps/web/src/assets/checkout-lock.svg",
"sanitizers": ["svgo", "svg-script-scan"],
"theme": "currentColor",
"owner": "design-platform"
}导出失败若表现为按钮不可用，先检查文件是否关闭了 viewer 的 copy/share/export；若导出的 SVG 字体错位，检查文本是否依赖本地字体以及消费端是否需要轮廓化；若图标尺寸大于画布，检查不可见图层、阴影和 bounding box。修复后应在实际 Web、iOS 或 Android 构建中渲染，而不是只在文件管理器里打开。
组件、变量与代码怎么建立映射
手工约定 Button 对应 button.tsx 可以起步，但规模扩大后必须让映射可检查。最小映射至少包含 Figma component key、variant/property 到代码 props 的转换、变量名到 token 的转换，以及源码 owner。自动生成片段只描述当前图层；真实组件还要承担语义标签、焦点、禁用、加载、埋点和响应式行为。
在 Organization 或 Enterprise 的适用场景中，Code Connect 可以把设计系统组件连接到真实代码片段，使 Dev Mode 优先显示团队组件用法，而不是通用自动生成代码。代码片段说明同时说明了自动片段、变量语法、插件扩展与 Code Connect 的差别。映射上线前要做两个反例：设计新增 variant 但代码没有对应 prop 时，检查应失败；代码删除 prop 但连接配置仍引用它时，发布应被阻断。
Figma REST API 适合在服务端读取文件元数据、节点与变量等受支持资源；Plugin API 在用户打开文件后运行，可读写画布对象并调用获准的外部 Web API。二者不能混为“后台万能脚本”。REST API 可以使用 OAuth、plan access token 或 personal access token，但用途不同：代表多个用户访问时优先 OAuth；组织级流水线可评估管理员管理的 plan token，但要注意其 beta 条件；个人本地脚本才使用 personal token。REST API 认证说明给出了三类凭证与 scope 的选择，scope 列表还强调 scope 不会越过文件本身的分享权限。
Plugin 通常由用户显式运行，并受 manifest 与 API 边界约束。插件开发与发布只能通过桌面应用，创建本地开发插件的当前入口见 创建开发插件。团队自建插件应在 manifest.json 把 networkAccess.allowedDomains 收紧到实际域名；完全不联网时设为 none。插件对未声明域名的请求会被 CSP 阻断，Plugin manifest 文档列出了网络白名单、动态 Page 加载和权限字段。大文件插件还应按需加载 Page，避免一次遍历整个文档导致明显卡顿。
调用 API 的脚本不要把个人 token 写进仓库。下面只展示安全的注入形态，<file-key> 与 <node-id> 都是虚构占位符：
export FIGMA_TOKEN='<access-token>'
curl --fail-with-body \
-H "X-Figma-Token: ${FIGMA_TOKEN}" \
"https://api.figma.com/v1/files/<file-key>/nodes?ids=<node-id>" \
-o figma-node.json
unset FIGMA_TOKEN成功时响应应包含请求节点及其 document 数据；403 优先检查令牌主体是否能访问文件，404 同时可能表示 file key/node id 错误或资源不可见，429 则读取 Retry-After、X-Figma-Plan-Tier、X-Figma-Rate-Limit-Type 和可用时的 X-Figma-Upgrade-Link 后退避，而不是并发重试。Figma 使用 leaky bucket，限流同时受 endpoint tier、调用者 seat 和资源所在 plan 影响，官方表格给出的每分钟上限还可能因流量和需求降低；流水线应批量请求、缓存结果、按 Retry-After 退避并设置有界重试，不能把某个 seat、endpoint 或 plan 的数值写成长期承诺。判断字段见 REST API 限流说明。响应文件可能包含文本、图片引用和内部命名，验证后应按数据分级清理，不要作为 CI artifact 永久保存。
版本、分支与库发布不是同一个动作
版本历史保存文件检查点。具有 can view 的成员可以浏览历史，只有 can edit 的成员才能创建、命名、删除版本信息或恢复版本；恢复是非破坏操作，恢复前后的检查点仍会保留，但后续评论不会因此消失。Starter 团队和 Drafts 的历史可见范围只有 30 天，Professional、Education、Organization 和 Enterprise 的保留能力不同于这个限制，实际应以文件所在团队的 plan 页面为准。版本历史指南还说明了复制版本、共享特定版本链接和恢复行为。
普通文件链接默认是 live link，打开时看到最新版本。历史版本链接也不是适合所有协作者的只读快照：官方说明要求协作者拥有 can edit 才能查看该历史版本，而且历史版本视图不能直接选择、复制或导出资产。需要交付可复核快照时，优先在当前文件保留专用交付 Page，再把 node ID、命名版本、导出文件哈希写入工单；如果必须冻结可编辑对象，可从目标版本复制出独立文件，但复制文件不会带上原文件的评论和版本历史。不要把动态链接、命名版本名或一个 PNG 单独当作回滚备份。
分支是隔离修改并评审后合并的工作区，适用于高风险组件库变化。它并非所有套餐都可用，创建者还需要相应 seat 与主文件访问权；分支评论不会在合并后进入主文件，library 也只能从 main file 发布。分支指南列出了这些限制。因此“分支评审通过”之后仍要合并、从主文件发布 library、由消费文件接受更新，并重新验证代码映射。
库发布的核心机制是：main component、style 和 variable 保存在 library file；发布后，消费文件收到可审查的更新，不会神奇地同步所有实现代码。具有消费文件编辑权限的人可以接受或忽略更新。Figma Libraries 指南说明了发布、启用和接受更新的链路。团队应记录“发布版本”和“消费版本”，否则一个产品文件接受了新库，另一个仍在旧库，视觉差异会被误认为前端 bug。
权限、席位和敏感数据要分层治理
Seat 决定成员能使用哪些产品能力，permission 决定成员能对具体 team、project、file 做什么。两者不是同一层。分享与权限指南说明了继承权限与显式文件权限；排查“能登录但不能改”“能看文件但没有 Dev Mode”时，必须分别检查这两层。
设计文件可能包含尚未发布的产品路线、客户名称、真实数据截图和内部 URL。默认做法应是 project 级最小可见、file 级按需授权、外部协作者使用明确 guest 身份，并关闭不必要的 public link 与 viewer copy/export。用于演示的数据必须脱敏；评论、版本历史、导出图片和插件请求同样属于数据边界，不能只清理画布可见文本。
Plugin 与第三方集成会扩大数据出口。准入时记录插件 owner、读取对象、写入对象、外部域名、保留期和撤销方法；不要因插件来自 Community 就默认可信。REST 自动化优先采用可转移的 OAuth app，或在满足套餐和 beta 风险要求时使用管理员管理的 plan token，并统一放入 Secret 管理器；禁止让团队流水线长期依赖员工 personal token。访问审计、SSO、SCIM、guest 控制等能力会受 plan 影响，团队采购前应从管理后台和官方能力页确认，不能把预期功能当作已开通功能。
常见故障要沿证据链定位
看不到 Dev Mode 或高级 Inspect：先看 seat，再看 plan，最后看 file permission。View/Collab 与 Dev/Full 的产品能力不同；给文件 can edit 也不会自动产生 Dev seat。
组件看似更新但消费文件没变化：确认修改对象是否 main component、更新是否从 main file 发布、消费文件是否启用该 library、更新是否被接受。分支中的改动还需要先合并。
变量显示值不显示名称：检查属性是否真正绑定 variable、变量是否来自可访问 collection、mode 是否覆盖到当前 Frame。手工填入相同色值不会自动建立变量关系。
导出按钮缺失或复制失败：检查 viewer copy/share/export 设置和对象权限。不要用截图绕过权限，因为这会绕过授权和资产来源记录。
桌面端字体正确、浏览器错误：确认浏览器是否安装或启用了 Font Installer、字体许可证是否允许团队使用、字体名称与字重是否一致。临时替换字体会改变换行和 Frame 高度，必须重新做视觉比较。
大文件卡顿或内存告警：先定位超大图片、隐藏复杂矢量、巨量组件变体和单 Page 对象数量，再拆 Page/文件和归档历史版本。关闭再开只能释放瞬时内存，不能消除对象复杂度。
从个人工具升级为团队交付系统
团队落地时，至少设置 design owner、library maintainer、developer representative 和 access admin 四种责任。小团队可以一人兼任，但责任不能消失。交付模板必须要求 Frame 链接、命名版本、Ready for dev 状态、组件与变量版本、工单、代码路径和验收证据；缺一项时，状态保持 Draft，而不是靠口头确认推进。
成本治理不要只数设计师人数。Full、Dev、Collab、View seat 对能力和费用影响不同，外部 guest、闲置 seat、组织库与高级治理能力也会改变总成本。按月复核“实际使用能力与 seat 是否匹配”，按季度抽查 library 接受延迟、detached instance、未映射变量、失效交付链接和个人 token。阈值应基于团队基线，而不是套一个通用数字。
退出平台前先导出关键文件与资产、记录 library 依赖、保存变量和组件映射、撤销 API token 与插件、迁移工单回链，再移除成员。Figma 文件导出不能自动保留所有评论、权限、版本和第三方集成语义，因此退出验收要在替代平台重新打开资产、解析 token、定位交付版本并完成一次代码实现，而不是只确认压缩包存在。
人员离职时，先转移 Drafts 和关键文件所有权，确认自动化不依赖其 token，再撤销组织、team、project、file 与第三方插件权限。最后用离职账号的无痕会话验证拒绝访问，并在审计记录中保存撤销证据。只停用邮箱而不检查共享链接和个人 token，会留下不可追踪的长期入口。
交付完成的判断标准
一份可进入开发的设计，不只是画布完成。开发应能从工单定位固定 Frame 与版本，识别组件和变量身份，读到符合项目单位的属性，下载可追溯资产，并把设计对象映射到代码组件；反向改变组件、变量、权限或版本后，团队也能看到明确失败证据并恢复。
当这条链路能够重复运行，Figma 才从在线画图工具变成设计交付系统。像素一致只是结果之一，更重要的是每次实现都能回答：依据哪个版本、用了哪个组件、变量从哪里来、谁批准了变化、失败后怎样回到上一个可信状态。