tailwind

Tailwind CSS（v4+）

概览

Tailwind CSS v4 技能，涵盖 CSS 优先配置、设计令牌、组件模式、shadcn/ui 集成、深色模式、容器查询、从 v3 迁移以及自定义工具类。

适用场景： 配置 Tailwind 主题、构建实用类优先组件、实现深色模式、使用容器查询、从 v3 迁移、集成 shadcn/ui、排查构建错误。

不适用场景： 不打算升级的 Tailwind v3 旧项目；使用其他样式方案（CSS Modules、styled-components）且不打算采用 Tailwind 的项目。

快速参考

模式	API	要点
CSS 优先配置	@theme { --color-brand: oklch(...); }	所有配置都在 CSS 中，无需 tailwind.config.js
导入入口	@import "tailwindcss";	替代 @tailwind base/components/utilities
自定义工具类	@utility name { ... }	替代 @layer utilities，支持变体
函数式工具类	@utility tab-* { tab-size: --value(--tab-size-*); }	通过 --value() 接受动态值
插件加载	@plugin "@tailwindcss/typography";	替代配置中的 require()
容器查询	@container 父级 + @md: 子级	内置功能，无需插件
命名容器	@container/sidebar + @md/sidebar:	将查询限定在特定容器中
深色模式变体	@custom-variant dark (&:where(.dark, .dark *));	基于类的深色模式覆盖
主题内联	@theme inline { --color-bg: var(--bg); }	在构建时内联值，仅适用于单一主题
源检测	@source "../node_modules/my-lib";	显式添加扫描路径
参考导入	@reference "../../app.css";	在 Vue/Svelte 作用域样式中使用主题
覆盖默认值	--color-*: initial; 在 @theme 中	重新定义前重置一个类别
动态值	grid-cols-(--my-var)	在工具类值中使用 CSS 变量
文本阴影	text-shadow-*	内置文本阴影工具类
起始样式	starting:opacity-0	用于进入动画的 @starting-style 变体
遮罩	mask-*	用于图像/渐变遮罩的 CSS mask 工具类
字段尺寸	field-sizing-content	自动调整文本区域和输入框尺寸
内嵌阴影	inset-shadow-*, inset-ring-*	内部阴影和环形工具类
用户验证	user-valid:, user-invalid:	用户交互后的表单验证
指针查询	pointer-fine:, pointer-coarse:	针对输入设备精度
惰性	inert:opacity-50	为惰性元素设置样式
逻辑间距	pbs-*, pbe-*, mbs-*, mbe-*	块方向的内边距/外边距（v4.2）
逻辑尺寸	inline-*, block-*, min-inline-*, max-block-*	逻辑宽度/高度工具类（v4.2）
逻辑内嵌定位	inset-s-*, inset-e-*, inset-bs-*, inset-be-*	逻辑定位；替代 start-*/end-*
逻辑边框	border-bs-*, border-be-*	块方向边框工具类（v4.2）
字体特性	font-features-['smcp']	OpenType font-feature-settings（v4.2）
新颜色调色板	mauve, olive, mist, taupe	额外的中性色调色板（v4.2）
Webpack 集成	@tailwindcss/webpack	将 Tailwind 作为 webpack 插件运行（v4.2）
色彩空间	OKLCH	v4 中的默认值，并生成 sRGB 回退值

常见错误

错误	正确做法
在 v4 中使用 tailwind.config.js	在 CSS 中通过 @theme { ... } 配置
对 hsl(var(--background)) 重复包装	直接引用：var(--background)
在 @layer base 中使用 :root/.dark	在根级别定义，不放在任何 @layer 中
对 @layer components 类使用 @apply	使用 @utility 指令定义自定义工具类
使用 @theme inline 实现多主题切换	动态主题使用不带 inline 的 @theme
到处使用 bg-blue-500 等原始颜色	使用会自动适配的语义化令牌（bg-primary）
使用 require() 或 @import 引入插件	使用 @plugin "package-name";
在 v4 中使用 tailwindcss-animate	改用 tw-animate-css
使用 shadcn/ui 时缺少 @theme inline	在 @theme inline 块中映射所有 CSS 变量
在 CSS 中使用 theme('colors.brand')	使用原生 CSS 变量 var(--color-brand)
使用已弃用的 start-*/end-* inset	使用逻辑工具类 inset-s-*/inset-e-*

委派

• 类模式探索和用法示例：使用 Explore Agent
• 跨多个文件从 v3 迁移到 v4：使用 Task Agent
• 设计令牌层级和主题架构：使用 Plan Agent

如果有 motion 技能，请将复杂的动画模式（弹簧物理、手势、滚动联动）委派给它。

参考资料

• 配置 -- CSS 优先配置、@theme、@theme inline、@utility、@plugin、@source、@reference、@variant 指令
• 设计令牌 -- OKLCH 令牌系统、品牌色阶、语义化令牌、阴影、z-index、流式排版
• 组件模式 -- 布局、网格、容器查询、3D 变换、subgrid、CVA 变体
• UI 模式 -- 按钮、表单、导航、卡片、带变体的排版、状态、无障碍
• 暗色模式 -- 基于类的暗色模式、多主题系统、ThemeProvider、@custom-variant
• shadcn/ui 集成 -- 四步架构、components.json、tw-animate-css、Vite 设置
• 迁移 -- 从 v3 迁移到 v4 的步骤、破坏性变更、升级工具、常见问题
• 故障排除 -- 常见错误、构建修复、CSS 层问题、PostCSS 问题