CSS变量应统一在:root声明，命名严格对应设计文档（如--color-primary-500），值用无单位数字，配合PostCSS+stylelint强制校验、Storybook实时比对及构建时自动生成tokens.json文档，实现设计与代码强一致。
用 CSS 自定义属性（CSS Variables）锚定设计系统值
设计规范里的颜色、间距、圆角这些值，硬编码在 CSS 里等于埋雷——改一次设计稿，就得全局搜 12px、#3b82f6 去替换，漏一个就错位。用 :root 定义变量，把设计 token 显式绑定到 CSS 层，才是可控的起点。
实操建议：
- 所有基础值（如
--space-xs、--color-primary、--radius-md）只在:root声明一次，不重复定义 - 变量名严格对应设计文档命名（比如设计稿写 “Primary / 500”，就叫
--color-primary-500，别简写成--primary） - 避免在变量值里嵌套计算，像
--space-lg: calc(var(--space-md) * 2)看似灵活，实际让设计师无法直接映射，也增加调试难度 - 变量值统一用无单位数字（间距用
4而非4px），再在使用处补单位，方便后续切换 rem/em
PostCSS + stylelint 强制校验 CSS 是否用了合规变量
光有变量没用，开发者随手写个 margin: 8px，工具不拦着，规范就形同虚设。PostCSS 插件 postcss-custom-properties 可以把变量编译为兼容写法，但真正起约束作用的是 stylelint 的规则链。
常见错误现象：本地开发没报错，上线后发现按钮圆角用了 6px 而不是设计规定的 var(--radius-sm)，视觉验收直接打回。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 启用
stylelint-config-standard后，加装stylelint-declaration-use-variable插件，锁定哪些属性必须用变量（如border-radius、color、margin） - 配置
ignoreProperties: ["font-size"]是合理妥协——字号常需语义化命名（--text-body），而非直连设计 token - CI 流程里跑
npx stylelint "**/*.css" --fix，失败即阻断合并，不靠人眼盯
Storybook 中用 Design Token 面板实时比对 CSS 与设计稿
开发时看组件样式，和设计师给的 Figma 或 Sketch 文件之间总有一层“脑内翻译”——padding: var(--space-md) 到底对应哪个数值？有没有被覆盖？靠截图比对效率低还易错。
使用场景：组件库维护、UI 重构、跨团队协作交付前核验。
实操建议：
- 在 Storybook 的
preview.js中注入设计 token 数据（JSON 格式），用插件@storybook/addon-designs关联 Figma 链接，再配合@storybook/addon-controls把变量做成可切换开关 - 每个故事（story）顶部加一个
TokenPanel组件，动态展示当前组件用到的--color-、--space-实际取值，点击可跳转定义源文件 - 禁用浏览器 DevTools 直接修改
style属性——它绕过变量体系，会掩盖真实问题；真要调试，改:root或对应组件的style属性值
构建时提取 CSS 变量生成设计文档快照
设计规范不是静态 PDF，它随项目演进。但开发者查一个间距值，还得翻 Confluence 或问设计师，说明变量体系没和代码真正打通。构建产物里带一份最新变量清单，比任何文档都准。
性能影响很小：提取只是读取 :root 块，生成 JSON，不参与运行时渲染。
实操建议：
- 用
postcss-custom-properties的preserve选项保持变量原样，再通过postcss-reporter或自定义脚本提取所有--*声明，输出为tokens.json - 把
tokens.json部署到项目文档页（如 VitePress 的/tokens/路由），支持搜索、按类型过滤，且带 Git 提交时间戳 - 禁止手动维护该 JSON——哪怕只改一行，也要走构建流程重生成，否则很快就会出现“文档写着
--space-xl: 40，实际代码是48”的撕裂
最麻烦的不是写规则，而是让所有人接受“CSS 不再是纯表现层，它是设计系统的 API”。变量命名、校验时机、文档同步，每个环节断掉一环，一致性就塌一半。
