必须选择w3c design tokens格式导出，确保type、value（对象结构）、description字段完整；style dictionary配置需匹配平台语义，指定transformgroup和css/variables format；验证css变量生效需检查:root作用域、文件加载及命名；命名应遵循三级规范并避免模糊引用。
导出的 JSON 必须符合 W3C Design Tokens 规范
很多团队卡在第一步：Figma 导出的 tokens.json 一导入 Style Dictionary 就报错或字段丢失。根本原因不是插件没装好，而是导出格式选错了。Figma Tokens 插件默认提供多种输出格式（CSS-in-JS、Tailwind、SCSS），但只有选 W3C Design Tokens 格式，才能保证 type、value、description 等关键字段被正确保留。
常见错误现象：
- 导出后
tokens.json里只有{"color": {"primary": "#4A6FF3"}}这种扁平结构 → 缺少type字段，Style Dictionary 解析失败 - 颜色值是
"#4A6FF3"，但期望的是{"hex": "#4A6FF3"}→ W3C 格式要求 value 是对象，不是原始字符串
实操建议：
- 在 Figma Tokens 插件导出界面，明确勾选 “W3C Design Tokens”，不要选 “CSS Variables” 或 “Tailwind Config”
- 导出前确认所有变量已设为
Public，私有变量不会被包含 - 导出后用 VSCode 打开
tokens.json，快速扫一眼是否有"type": "color"和"value": {"hex": "..."}结构
Style Dictionary 配置必须匹配目标平台语义
直接运行 style-dictionary build 却生成不出可用的 CSS 变量？问题常出在配置文件里没指定正确的 transform 和 format。CSS 自定义属性（var(--color-primary)）和 SCSS 变量（$color-primary）的生成逻辑完全不同，不能混用。
实操建议：
- 在
style-dictionary.config.js中，source指向src/tokens/tokens.json，platforms至少定义一个css平台 -
transformGroup必须设为['attribute/cti', 'name/cti/kebab']：前者确保 color/spacing/shadow 分类正确，后者把color.primary.500转成--color-primary-500 -
format设为css/variables，不是scss/variables或json/nested - 生成路径建议设为
build/css/tokens.css，然后在主样式入口里@import './build/css/tokens.css';
VSCode 里怎么验证 CSS 变量是否真生效
文件生成了，也引入了，但 var(--color-primary) 在浏览器里还是 undefined？别急着改配置，先确认三件事：CSS 文件是否被实际加载、命名是否拼错、作用域是否覆盖到目标元素。
实操建议：
- 打开浏览器开发者工具，在
Computed面板里找目标元素，看color属性右侧是否有var(--color-primary)显示为灰色（未解析）或彩色（已解析） - 检查生成的
tokens.css内容：开头必须是:root { --color-primary-500: #4A6FF3; }，而不是.color-primary-500 { ... } - 如果用 Shadow DOM 或 scoped styles，
:root不起作用 → 改用:host或直接在组件根元素上设置style="--color-primary-500: #4A6FF3;" - VSCode 中安装
Token Inspector插件，它能高亮var(--color-primary-500)并显示对应色值 —— 但前提是你的 CSS 文件路径在插件配置里被正确识别
命名冲突和层级覆盖最容易被忽略
设计令牌同步最隐蔽的坑不是技术链路断掉，而是同名变量在不同层级被覆盖。比如 Figma 里定义了 color.primary.base 和 color.primary.dark，但 CSS 里只用了 --color-primary，结果深色模式切换时颜色没变。
实操建议：
- 坚持用三级命名：用途 + 层级 + 状态，如
color-brand-primary-500、spacing-component-padding-md - 避免在 CSS 中写
color: var(--color-primary);这种模糊引用，明确写var(--color-brand-primary-500) - 如果要用主题切换，别靠 JS 动态改
:root，而是预生成两套 CSS：theme-light.css和theme-dark.css，用class="theme-dark"切换 - 每次更新 Figma Tokens 后，手动 diff 生成的
tokens.css，重点看新增/删减的变量名 —— 命名变更比值变更更容易引发线上样式断裂
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
