name: tailwind-patterns
description: “Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.”
risk: none
source: community
date_added: “2026-02-27”
Tailwind CSS 模式（v4 - 2025）
使用 CSS 原生配置的现代工具优先 CSS。
何时使用
在配置 Tailwind v4、使用 CSS 优先的主题和设计令牌，或实现容器查询和现代 Tailwind 模式时，使用此技能。
1. Tailwind v4 架构
与 v3 相比的变化
| v3（旧版） | v4（当前） |
|---|---|
tailwind.config.js | 基于 CSS 的@theme指令 |
| PostCSS 插件 | Oxide 引擎（快 10 倍） |
| JIT 模式 | 原生、始终开启 |
| 插件系统 | CSS 原生特性 |
@apply指令 | 仍然可用，但不推荐 |
v4 核心概念
| 概念 | 描述 |
|---|---|
| CSS 优先 | 在 CSS 中配置，而非 JavaScript |
| Oxide 引擎 | 基于 Rust 的编译器，速度快得多 |
| 原生嵌套 | 无需 PostCSS 的 CSS 嵌套 |
| 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; }何时扩展而非覆盖
| 操作 | 使用场景 |
|---|---|
| 扩展 | 在默认值之外添加新值 |
| 覆盖 | 完全替换默认刻度 |
| 语义令牌 | 项目特定的命名（primary、surface） |
3. 容器查询（v4 原生）
断点与容器对比
| 类型 | 响应对象 |
|---|---|
断点（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 grid-cols-[repeat(auto-fit,minmax(250px,1fr))] |
| 非对称（Bento） | grid grid-cols-3 grid-rows-2配合 span |
| 侧边栏布局 | grid grid-cols-[auto_1fr] |
注意：优先使用非对称/Bento 布局，而不是对称的 3 列网格。
7. 现代颜色系统
OKLCH 与 RGB/HSL 对比
| 格式 | 优势 |
|---|---|
| OKLCH | 感知均匀，更适合设计 |
| HSL | 直观的色相/饱和度 |
| RGB | 遗留兼容性 |
颜色令牌架构
| 层 | 示例 | 用途 |
|---|---|---|
| 原始值 | --blue-500 | 原始颜色值 |
| 语义 | --color-primary | 基于用途的命名 |
| 组件 | --button-bg | 组件特定 |
8. 字体系统
字体栈模式
| 类型 | 推荐 |
|---|---|
| Sans | 'Inter', 'SF Pro', system-ui, sans-serif |
| Mono | 'JetBrains Mono', 'Fira Code', monospace |
| Display | '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 变量、容器查询和原生特性。配置文件现在变得可选。
局限性
- 仅当任务明确匹配上述范围时才使用此技能。
- 不要将输出视为针对特定环境验证、测试或专家审查的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来询问澄清。
