name: tailwind-patterns
description: Tailwind CSS v4 原则。CSS优先配置，容器查询，现代模式，设计令牌架构。
allowed-tools: Read, Write, Edit, Glob, Grep
license: MIT
metadata:
version: “1.0.0”
domain: 前端
triggers: Tailwind CSS, Tailwind v4, 容器查询, 设计令牌, CSS优先
role: 专家
scope: 实施
output-format: 代码
related-skills: tailwind-design-system
Tailwind CSS 模式 (v4 - 2025)
使用CSS原生配置的现代实用优先CSS。
1. Tailwind v4 架构
从 v3 的变化
| v3 (旧版) |
v4 (当前版) |
tailwind.config.js |
基于CSS的 @theme 指令 |
| PostCSS 插件 |
Oxide 引擎 (10倍更快) |
| JIT 模式 |
原生，始终开启 |
| 插件系统 |
CSS原生特性 |
@apply 指令 |
仍然有效，但不推荐 |
v4 核心概念
| 概念 |
描述 |
| CSS优先 |
在CSS中配置，而非JavaScript |
| Oxide 引擎 |
基于Rust的编译器，速度更快 |
| 原生嵌套 |
CSS嵌套无需PostCSS |
| CSS变量 |
所有令牌暴露为 --* 变量 |
2. 基于CSS的配置
主题定义
@theme {
/* 颜色 - 使用语义名称 */
--color-primary: oklch(0.7 0.15 250);
--color-surface: oklch(0.98 0 0);
--color-surface-dark: oklch(0.15 0 0);
/* 间距尺度 */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 2rem;
/* 排版 */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
何时扩展与覆盖
| 操作 |
使用时机 |
| 扩展 |
添加新值到默认值旁 |
| 覆盖 |
完全替换默认尺度 |
| 语义令牌 |
项目特定命名 (主要, 表面) |
3. 容器查询 (v4 原生)
断点 vs 容器
| 类型 |
响应于 |
断点 (md:) |
视口宽度 |
容器 (@container) |
父元素宽度 |
容器查询用法
| 模式 |
类 |
| 定义容器 |
在父元素上使用 @container |
| 容器断点 |
在子元素上使用 @sm:, @md:, @lg: |
| 命名容器 |
使用 @container/card 提高特异性 |
何时使用
| 场景 |
使用 |
| 页面级布局 |
视口断点 |
| 组件级响应 |
容器查询 |
| 可重用组件 |
容器查询 (上下文无关) |
4. 响应式设计
断点系统
| 前缀 |
最小宽度 |
目标 |
| (无) |
0px |
移动优先基础 |
sm: |
640px |
大手机/小平板 |
md: |
768px |
平板 |
lg: |
1024px |
笔记本电脑 |
xl: |
1280px |
台式机 |
2xl: |
1536px |
大台式机 |
移动优先原则
- 先写移动样式 (无前缀)
- 添加更大屏幕覆盖使用前缀
- 示例:
w-full md:w-1/2 lg:w-1/3
5. 深色模式
配置策略
| 方法 |
行为 |
使用时机 |
class |
.dark 类切换 |
手动主题切换器 |
media |
遵循系统偏好 |
无用户控制 |
selector |
自定义选择器 (v4) |
复杂主题 |
深色模式模式
| 元素 |
浅色 |
深色 |
| 背景 |
bg-white |
dark:bg-zinc-900 |
| 文本 |
text-zinc-900 |
dark:text-zinc-100 |
| 边框 |
border-zinc-200 |
dark:border-zinc-700 |
6. 现代布局模式
Flexbox 模式
| 模式 |
类 |
| 中心 (双轴) |
flex items-center justify-center |
| 垂直堆叠 |
flex flex-col gap-4 |
| 水平行 |
flex gap-4 |
| 空间之间 |
flex justify-between items-center |
| 换行网格 |
flex flex-wrap gap-4 |
网格模式
| 模式 |
类 |
| 自适应响应 |
grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))] |
| 非对称 (Bento) |
grid grid-cols-3 grid-rows-2 带跨度 |
| 侧边栏布局 |
grid grid-cols-[auto_1fr] |
注意: 优先使用非对称/Bento布局而非对称3列网格。
7. 现代颜色系统
OKLCH vs RGB/HSL
| 格式 |
优势 |
| OKLCH |
感知均匀，设计更好 |
| HSL |
直观色调/饱和度 |
| RGB |
旧版兼容性 |
颜色令牌架构
| 层 |
示例 |
目的 |
| 原始 |
--blue-500 |
原始颜色值 |
| 语义 |
--color-primary |
基于目的的命名 |
| 组件 |
--button-bg |
组件特定 |
8. 排版系统
字体堆栈模式
| 类型 |
推荐 |
| 无衬线 |
'Inter', 'SF Pro', system-ui, sans-serif |
| 等宽 |
'JetBrains Mono', 'Fira Code', monospace |
| 显示 |
'Outfit', 'Poppins', sans-serif |
字体尺度
| 类 |
大小 |
使用 |
text-xs |
0.75rem |
标签, 说明文字 |
text-sm |
0.875rem |
辅助文本 |
text-base |
1rem |
正文文本 |
text-lg |
1.125rem |
引导文本 |
text-xl+ |
1.25rem+ |
标题 |
9. 动画与过渡
内置动画
| 类 |
效果 |
animate-spin |
连续旋转 |
animate-ping |
注意脉冲 |
animate-pulse |
轻微透明度脉冲 |
animate-bounce |
弹跳效果 |
过渡模式
| 模式 |
类 |
| 所有属性 |
transition-all duration-200 |
| 特定 |
transition-colors duration-150 |
| 带缓动 |
ease-out 或 ease-in-out |
| 悬停效果 |
hover:scale-105 transition-transform |
10. 组件提取
何时提取
| 信号 |
操作 |
| 相同类组合3+次 |
提取组件 |
| 复杂状态变体 |
提取组件 |
| 设计系统元素 |
提取 + 文档化 |
提取方法
| 方法 |
使用时机 |
| React/Vue 组件 |
动态, 需要JS |
| CSS中的@apply |
静态, 无需JS |
| 设计令牌 |
可重用值 |
11. 反模式
| 不要 |
要 |
| 到处使用任意值 |
使用设计系统尺度 |
!important |
正确修复特异性 |
内联 style= |
使用实用类 |
| 重复长类列表 |
提取组件 |
| 混合 v3 与 v4 配置 |
完全迁移到CSS优先 |
大量使用 @apply |
优先使用组件 |
12. 性能原则
| 原则 |
实施 |
| 清除未使用 |
v4 中自动 |
| 避免动态性 |
不使用模板字符串类 |
| 使用 Oxide |
v4 默认, 10倍更快 |
| 缓存构建 |
CI/CD 缓存 |
记住: Tailwind v4 是CSS优先。拥抱CSS变量、容器查询和原生特性。配置文件现在是可选的。