<p>@theme 必须严格位于 @import 'tailwindcss'; 之后、同一 CSS 文件中，且变量名需带 --color- 等标准前缀；仅 OKLCH 格式支持自动色阶推导，跨文件不生效，不报错但自定义工具类将缺失。</p>
@theme 必须写在 @import 'tailwindcss'; 之后
这是最容易失效的点：Oxide 引擎只在 @import 'tailwindcss'; 出现后的同文件、同作用域内解析 @theme。如果它被写在前面、嵌套在 @layer 里，或分散在另一个 CSS 文件中，自定义颜色、间距等将完全不生效，且无任何错误提示。
常见错误现象包括：bg-primary-500 渲染成透明、text-surface 不识别、所有自定义色阶（如 -400/-600）缺失。
-
@theme块必须出现在同一 CSS 文件中，且严格位于@import 'tailwindcss';下方 - 变量名必须带标准前缀：
--color-primary✅，--primary❌，--my-color❌ - 值支持 HEX/RGB/HSL，但只有 OKLCH（如
oklch(0.7 0.15 250)）才能触发自动明度推导（生成primary-400/primary-600等） - 跨文件不继承 —— 想全局生效，就得统一写进主入口 CSS（如
src/index.css）
@theme 只影响当前 CSS 文件作用域
和 tailwind.config.js 的全局行为不同，@theme 是 CSS 原生作用域机制：它只对当前文件中后续出现的工具类生成起效，不会污染其他 CSS 文件，也不会影响 JS 中的 theme() 函数调用。
这意味着如果你在 components/Button.css 里写了 @theme { --color-brand: #ef4444; }，这个 --color-brand 不会触发 bg-brand-500 类生成 —— 因为 Oxide 引擎只在主入口文件里扫描 @theme 并生成工具类。
立即学习“前端免费学习笔记（深入）”；
- 想让自定义颜色可用，
@theme必须写在被构建工具识别为“Tailwind 入口”的那个 CSS 文件里（通常是src/index.css或src/styles/main.css） -
@theme中的变量可被 JS 动态修改（如document.documentElement.style.setProperty('--color-brand-500', '#ef4444')），但仅限已声明的合法前缀变量 - 不能在
@theme里引用其他 CSS 变量（如var(--color-base)），也不支持表达式或函数
OKLCH 是唯一能推导色阶的格式
如果你希望 bg-primary-400、text-primary-600 这类带明度层级的类自动出现，必须用 OKLCH 写色值。HEX、RGB、HSL 都只会生成 primary-500 单一色阶，其余全部静默跳过。
例如：--color-primary: #3b82f6; → 只有 primary-500；而 --color-primary: oklch(0.62 0.15 274); → 自动推导出 primary-50 到 primary-900 全系列。
- OKLCH 值可通过在线转换器从 HEX 生成（搜索 “HEX to OKLCH”）
- 暗色模式下，Oxide 会基于同一 OKLCH 基础值自动调整明度，无需额外声明
dark:变体 - 若项目需兼容旧浏览器，注意 OKLCH 在 Safari 16.4+、Chrome 111+ 才完整支持；降级方案仍需 fallback HEX
@theme 和 @config 的分工不能混淆
@theme 不是 @config 的替代品，二者定位完全不同：@config 是静态初始化区（必须在 @import 前），只接受字面量；@theme 是运行时可变区（必须在 @import 后），支持 JS 动态注入。
比如你想改默认 spacing，用 @config 写死：@config { theme: { spacing: { 4: '1rem', 8: '2rem' } } }；但想让间距随用户偏好切换，就得用 @theme 声明 --spacing-unit，再在 JS 里改它。
-
@config不支持变量、函数、计算值；写错语法（如漏逗号、多引号）会导致整块被忽略 -
@theme的变量名前缀必须与 Tailwind 内部约定一致（--color-、--spacing-、--font-size-），否则引擎无法映射到工具类 - 两者都只作用于当前 CSS 文件，不存在“合并配置”逻辑 —— 多个入口文件就得各自配
