Figma AI v2.4 导出 JSON 时，变量名混乱、层级缺失、甚至整组变量凭空消失——如果你的项目也踩过这个坑，原因其实很明确：变量组的命名没有遵循 AI 能理解的“语义规则”。具体来说，组名必须以 color_、space_、text_、radius_、border_ 之一开头，全英文、无空格，子项用小驼峰；否则 AI 会直接跳过该组，导出的 JSON 里自然就缺了关键的 category 字段。

当你用 Figma AI v2.4 创建变量组（颜色、间距、文字样式等），满怀期待导出 JSON 准备喂给 Style Dictionary 或 Theo 时，却发现结构一团糟。问题根源就在于：Figma AI v2.4 对变量组名称有严格的语法偏好——它会把下划线前缀当作分类标识，把驼峰式子项当作可提取的值。一旦出现空格、中文或特殊符号，导出就会中断或字段丢失。

变量组命名必须满足 AI 解析前提

AI v2.4 在扫描变量组时，只信任那些以特定前缀开头、不含空格且全英文的名称。如果你起了“主色系”或“Spacing 8px”这样的名字，AI 会直接跳过该组，不会把它纳入 tokens 导出范围。那该怎么办？

第一步：在左侧资源面板（Assets → Variables）中，点击“+ Add variable set”新建变量组。

第二步：输入组名时，必须从 color_、space_、text_、radius_、border_ 之一开头，例如 color-primary、space-layout、text-heading-lg、radius-card、border-input。

第三步：组内变量名禁用空格与连字符，使用小驼峰格式，比如 primary500、baseXs、h1Bold、sm、defaultSolid。AI 会根据这些命名自动推断类型与层级。

第四步：避免嵌套同名变量组。比如不要同时存在 color-primary 和 color_primary；AI v2.4 会把后者识别为独立组而非子集，导致导出 JSON 中间出现重复键冲突。

启用 Dev Mode 并导出结构化变量 JSON

Dev Mode 是 Figma 原生支持的变量导出通道，v2.4 版本已经优化了对自定义前缀组的识别逻辑，不需要额外插件就能输出带 category 字段的合规 JSON。

点击右上角“Design”旁边的“Dev Mode”开关，确保它处于开启状态。然后在左侧资源面板展开 Variables → 找到你刚创建的变量组（比如 color-primary），点击右侧三点菜单 → “Export as JSON”。

导出的文件名是 {变量组名}.json，内容中会包含 "category": "color"、"type": "color" 等字段——这些元数据是 AI v2.4 自动注入的。如果导出 JSON 里没有 category 字段，说明组名没有匹配前缀规则。

批量校验与修复变量组命名

项目里已经有几十个变量组，命名杂乱不堪，手动一个一个改显然不现实。Figma v2.4 支持通过 AI 指令批量修正，前提是原始命名中保留了可识别的语义线索（比如包含“btn”“bg”“text”等词）。

方法一：使用内置 AI 重命名指令

在变量面板空白处右键 → “Rename variable sets with AI”。输入 Prompt 类似：“将所有含‘bg’的变量组重命名为 color-surface-{后缀}，含‘text’的重命名为 text-{后缀}，含‘gap’的重命名为 space-{后缀}，全部转为小写字母加短横线格式”。

方法二：运行 MCP Server 校验脚本

在支持 MCP 的 IDE（如 Cursor）中执行：run validate_variable_naming --file-id=abc123xyz --strict-mode=true。这条命令会扫描所有变量组，标记出不符合 color_/space_/text_ 前缀的条目，并生成修复建议清单。例如：“border-main → border-main”（合规），“spacing-16 → space-layout”（需重命名）。