必须用 theme.extend.colors 添加新颜色变量，直接赋值 theme.colors 会清空内置色板；新增 brand、surface 等键名不覆盖默认类，保留 text-gray-700 等原有功能；需配置 content 覆盖所有使用路径，且值必须为静态字面量。
用 theme.extend 添加新设计变量，不碰默认值
直接写 theme.colors = { ... } 会清空所有内置颜色（bg-gray-100、text-blue-500 全失效），这是最常踩的坑。必须用 extend 嵌套新增，保留原有体系：
-
extend下新增的键名（如brand、surface）不会覆盖默认色板 - 内置类仍可照常使用：
text-gray-700、bg-emerald-500全部有效 - 团队新人能同时理解设计规范（
text-brand-600）和通用语义（text-primary）
示例配置：
theme: {
extend: {
colors: {
brand: {
50: '#f8fafc',
100: '#e2e8f0',
500: '#3b82f6',
900: '#1d4ed8'
},
surface: {
DEFAULT: '#ffffff',
muted: '#f1f5f9'
}
},
spacing: {
'3.5': '0.875rem',
'18': '4.5rem',
'128': '32rem'
}
}
}
把设计规范映射到实用类前缀，避免语义混淆
Tailwind 默认的 bg-blue-500 是“蓝”，但你的设计系统里它叫“主色”。如果直接改 colors.blue，会导致所有依赖 blue 的第三方组件样式错乱。更安全的做法是：用新前缀承载设计语言。
- 新增
brand色系后，统一用bg-brand-500、text-brand-900表达设计规范 - 保留
blue作为技术备用色（比如图表配色、调试边框） - 在 Figma 或设计文档中标注：「
brand-500= 主按钮背景色」，而非「blue-500= 主按钮背景色」
用 content 扫描范围确保自定义类被识别
Tailwind JIT 模式只生成实际用到的类。如果你在组件里写了 bg-brand-500，但 tailwind.config.js 的 content 没覆盖该文件路径，构建时这个类就根本不会生成——页面上什么颜色都没有，连报错都不会有。
立即学习“前端免费学习笔记（深入）”；
- 检查
content数组是否包含你写自定义类的所有位置（JSX/TSX/Vue/MDX 文件） - 常见漏项：
./src/components/**/*.{js,jsx,ts,tsx}忘了.mdx，导致文档站点样式丢失 - 开发时可临时加
console.log在组件中输出bg-brand-500字符串，确认它被扫描到
设计规范要能被静态读取，别用运行时逻辑
你在 theme.extend.colors.brand 里写的值，会被 theme() 函数在构建时静态解析。这意味着不能写 brand: () => getBrandColorFromEnv() 这种动态逻辑——JIT 编译器看不懂函数调用。
- 多环境主题（如 dark/light）应通过独立配置文件实现，例如
tailwind.config.dark.js - 需要动态切换的设计变量（如品牌色随租户变化），得靠 CSS 自定义属性 +
var(--brand-500)配合，而不是 Tailwind 类名 - 所有
theme()调用必须指向字面量或静态对象，比如theme('spacing.18')可以，theme('colors.brand.' + level)不行
真正难的不是写配置，而是让设计师、前端、后端对同一串字符串（brand-500）达成共识，并且确保它在任何构建环节都不被遗漏或误解释。
