必须用@theme块声明且变量名带固定前缀，tailwind.config.js中写var(--x)完全无效；@import"tailwindcss";须在@theme前，断点/字体/间距等均需严格匹配--breakpoint-、--font-、--spacing-等前缀，否则类静默不生成。
必须用 @theme 块声明，且变量名带固定前缀；tailwind.config.js 里写任何 var(--x) 都无效，不是配置错，是根本不会解析。
变量名必须带 --color-、--radius- 等前缀
Tailwind v4 的 Oxide 引擎只扫描特定前缀的 CSS 自定义属性，拼错或漏连字符就等于没写：
-
--color-primary: oklch(0.55 0.27 262);→ ✅ 生效bg-primary、text-primary -
--radius-card: 0.75rem;→ ✅ 生效rounded-card -
--shadow-glow: 0 8px 24px rgb(0 0 0 / 0.15);→ ✅ 生效shadow-glow -
--primary: #3b82f6;或--my-radius: 0.5rem;→ ❌ 完全不识别，类不会生成
@import "tailwindcss"; 必须在 @theme 前，且不能拆开
v4 废弃所有 @tailwind 指令，只认标准 CSS @import，顺序和写法错一个，整个主题系统静默失效：
- ✅ 正确：
@import "tailwindcss";（单引号、末尾分号不可少） - ✅ 正确：该行之后紧跟
@theme { --color-primary: ...; } - ❌ 错误：
@tailwind base;+@tailwind utilities;→ 基础类全不生成 - ❌ 错误：
@import "tailwindcss"（缺分号）→ 构建可能卡住或跳过 - ❌ 错误：把
@theme写在未被 PostCSS 处理的文件里（如组件内style标签）→ 变量不参与编译
断点、字体、间距变量也走同一套规则
所有主题维度都统一用 @theme 声明，但前缀不同，不能混用：
立即学习“前端免费学习笔记（深入）”；
- 断点：必须
--breakpoint-xl2: 1920px;→ 支持xl2:w-full，不能写--xl2 - 字体：必须
--font-sans: "Inter", sans-serif;→ 支持font-sans - 间距：推荐
--spacing-6: 1.5rem;→ 支持p-6，不建议用--size-6（非标准前缀） - 圆角/阴影等同理，命名必须严格匹配工具类逻辑，比如
--radius-lg对应rounded-lg
动态切换要靠 data-theme，不是 dark:
dark: 是硬编码映射系统偏好，对自定义主题完全无感。想切深色/紫色/高对比等任意主题，只能走 CSS 变量层级：
- ✅ 正确：
:root { --color-bg: #fff; }+[data-theme="dark"] { --color-bg: #111; } - ✅ 切换只需一行 JS：
document.documentElement.dataset.theme = "dark"; - ❌
dark:bg-gray-900不会响应data-theme="dark"，它只认prefers-color-scheme或class="dark" - ⚠️ 注意：变量必须挂载在
:root或html上，设在body或局部组件会丢失继承
最容易被忽略的是变量初始化时机——JS 设置 data-theme 前，CSS 文件若未完成解析，浏览器会先按旧值渲染一帧。内联默认变量 + 统一命名（别混用 --primary 和 --color-primary）比写十个切换函数更关键。
