css组件库颜色必须语义化命名（如--color-brand-primary）、hex格式声明、:root设默认值、组件内仅用var()引用并带fallback，主题切换需覆盖而非替换变量。
CSS组件库的颜色命名和色值格式必须语义化、可维护、跨主题一致——不能靠设计师给的“那个蓝”或开发者写的#007bff硬编码来推进。
用语义角色而非物理值命名颜色变量
命名直接暴露用途，而不是色相或明度。比如--color-brand-primary比--color-blue-500更可靠，因为后者在品牌色从蓝色换成青绿色时就失效了；而前者只承诺“这是品牌主色”，值可以随时换，下游组件完全无感。
- 品牌色用
--color-brand-primary、--color-brand-accent，不带状态（hover/disabled） - 功能色必须绑定语义：
--color-success、--color-error、--color-warning，不是“绿/红/黄” - 中性色按灰阶+用途组合：
--color-gray-100（背景）、--color-gray-700（正文）、--color-gray-300（边框） - 禁用
--color-light、--color-dark这类模糊词，它们在深色模式下会彻底反直觉
HEX格式是组件库最稳妥的色值落地方式
虽然HSL/OKLCH适合动态推导，但组件库交付的是稳定、可验证、设计-开发对齐的产物。HEX能确保每个变量值在所有浏览器、工具链、设计稿标注中1:1一致，不会因HSL参数顺序或浏览器解析差异导致微小偏色。
- 所有
:root中声明的色值统一用#RRGGBB或#RGB格式，例如--color-primary: #3b82f6 - 避免在
:root里写hsl(210, 70%, 55%)——它无法被Figma插件、VS Code Color Highlight等工具直接识别为色块 - 如果需要悬停/禁用变体，用独立变量声明：
--color-primary-hover、--color-primary-disabled，而不是依赖运行时hsl()计算（组件库要保证SSR和静态渲染一致性） - HEX值必须来自设计系统源文件，禁止人工“目测调色”后手写，否则每次同步都可能漂移
组件内只允许用var()引用，且必须带fallback
组件样式表里出现任何硬编码色值（如background-color: #3b82f6）都是破坏封装性的bug。变量未定义时，浏览器不会报错，但文字可能变透明、按钮可能消失——尤其在微前端子应用未加载主题CSS时。
- 所有颜色属性强制使用
var(--color-primary, #007bff)，第二个参数是字面量fallback，不能是另一个var() - 伪类状态也必须走变量：
:hover { background-color: var(--color-primary-hover, #2563eb); } - 禁止在组件选择器内部覆盖根变量，例如
.card { --color-primary: red; }——这会让父级主题切换失效，且无法被外部JS控制 - SVG图标中的
fill和stroke同样要用var()，否则深色模式下图标会卡死在浅色
主题切换必须默认值兜底，不能依赖媒体查询独占
很多团队把所有颜色塞进@media (prefers-color-scheme: dark)，结果用户手动切主题或加载失败时，页面一片白底黑字——因为:root里根本没定义默认值。
-
:root必须声明全部基础变量的浅色默认值，例如--color-bg-surface: #ffffff - 深色模式只覆盖差异项：
@media (prefers-color-scheme: dark) { :root { --color-bg-surface: #111827; } } - 用户主动切换主题时，用
data-theme="dark"类配合[data-theme="dark"] { --color-bg-surface: #111827; }，不要删掉:root默认值 - JS批量注入主题时，变量名必须和CSS中完全一致（区分大小写），拼错如
--color-prmiary会被浏览器静默忽略，无任何提示
最常被忽略的一点：组件库的CSS变量不是“写完就跑”，它必须和设计系统的Token JSON、Figma变量、构建时的对比度检查打通。否则哪怕命名再规范，一个没进自动化流水线的色值更新，就会让整套体系在两周后开始松动。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
