CSS变量本身不解决多端统一问题，真正起作用的是Token命名规范+工具链协同；--btn-primary-bg这类绑定组件+状态+用途的变量名会切断设计系统与各端映射能力，导致Figma插件无法识别类型、下游平台无法类型校验、暗色模式需重复定义、React Native生成语义错位常量等问题。
CSS变量本身不解决多端统一问题，真正起作用的是Token命名规范 + 工具链协同 —— 没有规范的变量名，哪怕全用--开头也照样混乱。
为什么--btn-primary-bg这种命名在多端项目里是灾难
这类绑定组件+状态+用途的变量名，看似直观，实则切断了设计系统与各端实现的映射能力：
- 无法被Figma插件（如Tokens Studio）识别为标准
color类型，导出JSON时变成字符串，下游平台（iOS/Swift、Android/Kotlin、Web/SCSS）无法做类型校验或自动转换 - 暗色模式切换时，
--btn-primary-bg需要重定义，但--color-primary-500只需在主题层重新计算一次，所有用到它的组件（按钮、标签、卡片边框）自动适配 - React Native不支持
var()，必须靠工具把--color-primary-500转成Colors.primary500；如果原始变量名含btn，生成的JS常量就变成BtnPrimaryBg，语义错位且无法复用
:root里只放空壳变量，实际值由[data-theme]注入
不要在:root里直接写死颜色值。正确做法是声明“占位符”，让主题层决定含义：
:root {
/* 所有变量都带 fallback，确保未覆盖时有基础可用值 */
--color-primary-500: #2563eb;
--color-error-500: #ef4444;
--space-md: 12px;
--radius-lg: 12px;
}
<p>/<em> 明色主题 </em>/
:root[data-theme="light"] {
--color-primary-500: #2563eb;
--color-error-500: #ef4444;
}</p><p>/<em> 暗色主题 </em>/
:root[data-theme="dark"] {
--color-primary-500: #3b82f6;
--color-error-500: #f87171;
}- JS切换主题只需
document.documentElement.setAttribute('data-theme', 'dark')，无需遍历修改每个变量 - 构建工具（如Style Dictionary）能基于同一套
tokens.json分别输出Web CSS、iOS Swift enum、Android XML dimen，前提是变量名符合color-{semantic}-{scale}结构 - 禁止在
:root里用color-mix()或calc()动态算色——这些计算应放在主题CSS文件中，保证Token源文件纯静态、可校验
Token命名必须分层：语义 + 用途 + 尺度，三者缺一不可
一个合格的Token名要让人一眼看出它是什么、在哪用、有多深：
立即学习“前端免费学习笔记（深入）”；
-
--color-primary-base：基础品牌色，仅用于派生其他色阶，不直接上屏 -
--color-primary-500：主按钮背景、高亮文字等核心交互态，对应设计系统中的500色阶 -
--color-border-default：非状态类边框，由--color-primary-100或--color-neutral-200生成，不写死值 -
--space-md：不是--padding-md——同一数值可能用于margin、gap、padding，绑定用途会反向限制UI灵活性 -
--radius-sm：圆角尺寸，不叫--card-radius，因为sm也可能用于Tag、Avatar、Input
所有名称必须小写、用短横线分隔，避免大驼峰或下划线，否则Figma导出和Style Dictionary解析会失败。
构建时校验Token完整性比运行时更重要
很多团队等到上线才发现--color-success-500在暗色主题里没定义，页面白屏——这不该发生在浏览器里。
- 用
postcss-custom-properties开启preserve: false+warnings: true，构建时报出未定义变量引用 - 在
tokens.json中强制要求每个Token包含type（color/dimension/fontFamily）和description字段，CI阶段用ajv校验Schema - 禁止在CSS中嵌套
var(--color-primary-500, var(--color-primary-base))——fallback必须是字面量，否则工具链无法静态分析依赖链
真正卡住多端一致性的，从来不是技术上限，而是Token定义那一刻有没有人盯着命名看三秒：它能不能脱离当前组件、当前平台、当前主题单独存在。
