必须在@layer base中定义:root，因其确保最低优先级、避免与tailwind内置样式冲突，并使媒体查询和[data-theme]切换能正确覆写变量；变量名须以--开头，引用需用bg-[var(--x)]等任意值语法。
必须在 @layer base 中定义 :root，否则变量无法被 Tailwind 工具类正确引用或被媒体查询覆盖。
为什么 :root 必须写在 @layer base 里
Tailwind 的 @tailwind base 指令会注入重置样式（如 *, ::before, ::after { box-sizing: border-box }），这些样式依赖最低优先级。如果你把 :root 写在 @tailwind base 之后、或直接写在普通 CSS 文件顶部，它可能被后续 @layer base 内容覆盖，或与 Tailwind 自带的 :root 行为冲突（比如 v4 新增的 @theme 块）。
更关键的是：媒体查询（如 @media (prefers-color-scheme: dark)）和 [data-theme="dark"] 选择器，只有作用于同一层级的 :root 才能有效覆写变量值。写在 @layer base 外，就脱离了这个“主题变量作用域”。
-
@layer base确保你的:root是整个样式表中最早生效的一批声明 - 所有主题切换逻辑（深色模式、多主题）都基于这个基础层展开
- 避免在
@layer components或@layer utilities中重复定义:root—— 它们不处理全局作用域
-- 开头是硬性要求，拼错就彻底失效
Tailwind 对任意值语法（如 bg-[var(--primary)]）不做变量存在性校验。如果写成 --primary-color 却在引用时漏了 -（比如 var(--primarycolor)），浏览器找不到该变量，最终计算为 unset 或 inherit，背景/颜色直接消失，且控制台不会报错。
- 变量名必须以
--开头，这是 CSS Custom Property 的语法强制约束 - 推荐统一命名风格，例如全部小写 + 连字符：
--color-primary、--space-sm - 不要用下划线或驼峰：
--colorPrimary或--color_primary在部分旧版 Safari 中有兼容问题
如何安全地在工具类中引用这些变量
不能靠 tailwind.config.js 的 theme.extend.colors 直接填 var(--x) —— Tailwind 构建时无法解析运行时变量，会导致 hover/focus 变体生成失败，甚至构建报错 Cannot read property 'r' of undefined。
真正可用的方式只有两种：
- 用
bg-[var(--color-bg)]这类任意值语法，直接写在 class 属性里（支持响应式前缀，如md:bg-[var(--color-bg)]） - 在
@layer utilities中手动定义工具类：.bg-primary { background-color: var(--color-primary); }，再配合@apply bg-primary - 绝对不要在
@apply里写@apply bg-[var(--x)]——@apply不支持插值，会被当作文本字面量处理
深色模式切换必须绑定到
仅靠 @media (prefers-color-scheme: dark) 不够稳定：用户系统设置变更后，页面不会自动重绘；且无法支持手动切换（比如页面右上角“日/夜模式”按钮）。
可靠方案是用 data-theme 属性 + JavaScript 控制：
-
data-theme必须加在标签上，而不是或某个容器 —— 否则[data-theme="dark"] :root选择器无法命中 - 在
@layer base中这样写：[data-theme="dark"] { --color-bg: #111827; --color-text: #f9fafb; } - 切换时只需
document.documentElement.setAttribute('data-theme', 'dark')，无需重载或重新计算样式
变量本身不“感知”变化，但浏览器会实时重计算所有 var(--x) 引用 —— 这个机制很轻量，但前提是变量定义位置和作用域完全正确。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
