最轻量可维护的跨项目调色板共享方式是CSS自定义属性，需分层定义基础色与主题色、避免全局污染、通过npm发布纯CSS包、构建期用PostCSS注入、JS仅读取不硬编码。
用 CSS 自定义属性（CSS Variables）统一管理调色板
直接把颜色抽成 --primary、--surface-1 这类自定义属性，是目前最轻量、最可维护的跨项目共享方式。它不依赖构建工具，浏览器原生支持，且能被 JS 动态读写。
关键不是“怎么定义”，而是“定义在哪一层”。常见错误是把所有调色板塞进一个 :root，结果项目 A 用了深色模式变量，项目 B 却只想要浅色基础色 —— 最终要么覆盖冲突，要么冗余加载。
- 把基础色（如品牌蓝、中性灰）放在独立的
base-colors.css文件里，用:root声明 - 把主题色（如
--theme-dark、--theme-high-contrast）拆到单独文件，通过class或data-theme切换作用域，例如：:root[data-theme="dark"] { --bg: #121212; --text: #e0e0e0; } - 项目引用时，优先
@import基础色，再按需加载主题文件；避免在组件内部重复声明同一变量
通过 npm 包发布和消费 CSS 调色板
如果你有多个前端项目（React/Vue/纯 HTML 都有），又希望版本可控、语义化更新（比如 v2.1.0 加了新的无障碍对比色），那就该走 npm 包路线。但别打包成 JS 模块导出颜色对象 —— 那会割裂 CSS 生态，导致无法用 var(--primary) 直接消费。
真正可行的做法是：发布纯 CSS 包，内容只有 :root 和作用域规则，无 JS、无构建产物。
立即学习“前端免费学习笔记（深入）”；
- 包结构保持极简：
index.css（主入口）、themes/dark.css、colors/base.css - 发布前确保所有变量名带命名空间，比如
--mylib-primary，避免和宿主项目冲突 - 消费时不要
import 'mylib-colors'（这是 JS 导入），而要用@import 'mylib-colors/index.css'或<link rel="stylesheet" href="node_modules/mylib-colors/index.css"> - 注意 PostCSS 或 Vite 的
@import解析路径问题：有些工具默认不解析 node_modules 下的 CSS@import，需配postcss-import或开启css.resolve.alias
PostCSS 插件动态注入调色板（适合设计系统团队）
当调色板需要从 JSON 配置生成、或要对接 Figma Token、或需运行时根据环境变量输出不同变量集时，硬写 CSS 就太僵了。这时候 PostCSS 是更可控的选择，但容易踩“构建时机”和“变量覆盖”的坑。
典型错误是用 postcss-custom-properties 去“编译”变量 —— 它只是静态替换，无法解决多主题切换，反而让调试变难。
- 推荐用
postcss-advanced-variables或自研插件，在构建期将colors.json注入到:root中，生成带注释的源码（方便排查） - 务必保留原始变量名不变，不要把
"primary": "#3b82f6"编译成color: #3b82f6—— 这样就失去 CSS 变量的层叠与响应能力 - 如果项目同时用 Sass/Less，别试图用它们的变量去“桥接”CSS 自定义属性；Sass 编译时已固定值，无法被 JS 修改，和 CSS 变量定位完全不同
避免在 JS 中硬编码颜色值同步调色板
有人为了“统一”，在 JS 里写个 const COLORS = { primary: '#3b82f6' }，再用内联样式或 className 动态设置 —— 这看似可控，实则破坏了 CSS 的层叠、伪类、媒体查询能力，还让深色模式切换变得异常脆弱。
真正需要 JS 介入的场景其实很少：比如 Canvas 绘图、SVG fill 属性、或第三方图表库不支持 CSS 变量。其余情况，都该让 CSS 自己解决。
- JS 只读取
getComputedStyle(document.documentElement).getPropertyValue('--primary')，用于必要计算，绝不反向写入 - 如果必须动态设色（如用户自定义主题），用
document.documentElement.style.setProperty('--primary', newColor)，而非改 class 或 style - 警惕 React 的
style={{ color: COLORS.primary }}—— 它绕过了 CSS 变量链，一旦设计系统升级新色值，这里不会自动更新
调色板共享最难的不是技术实现，而是约定变量命名层级和作用域边界。比如 --color-brand-primary 和 --color-ui-accent 看似相似，但前者属于品牌规范，后者属于组件逻辑 —— 混在一起就会让下游项目无法安全地做主题覆盖。
