# Tailwind Patterns

> Tailwind CSS v4 原则。CSS-first 配置、容器查询、现代化模式与 Design Token（设计令牌）架构。

- Skill: `misonl/tailwind-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add misonl/tailwind-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/misonl/tailwind-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: misonl (https://skillmd.com/u/misonl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/misonl/tailwind-patterns

---


# Tailwind CSS 模式（v4，2025）

> 采用 CSS 原生配置的现代 Utility-first CSS（工具优先）。

---

## 1. Tailwind v4 架构

### 相比 v3 的变化

| v3（Legacy） | v4（Current） |
|-------------|---------------|
| `tailwind.config.js` | 基于 CSS 的 `@theme` 指令 |
| PostCSS plugin | Oxide 引擎（约 10x 更快） |
| JIT mode | 原生内建、始终开启 |
| Plugin system | CSS 原生能力增强 |
| `@apply` directive | 仍可用，但不推荐重度依赖 |

### v4 核心概念

| 概念 | 说明 |
|------|------|
| **CSS-first（CSS 优先）** | 配置写在 CSS 中，而不是 JavaScript |
| **Oxide Engine** | Rust 编译引擎，速度更快 |
| **Native Nesting** | 不依赖 PostCSS 的 CSS 嵌套 |
| **CSS Variables** | 设计 token 通过 `--*` 变量暴露 |

---

## 2. 基于 CSS 的配置

### 主题定义

```
@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  
  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}
```

### 何时扩展与覆盖

| 动作 | 适用场景 |
|------|----------|
| **Extend** | 在保留默认值的同时新增 |
| **Override** | 需要整体替换默认刻度体系 |
| **Semantic tokens** | 采用项目语义命名（primary、surface） |

---

## 3. 容器查询（v4 原生）

### Breakpoint 与 Container 的区别

| 类型 | 响应对象 |
|------|----------|
| **Breakpoint（断点）** (`md:`) | 视口宽度（viewport） |
| **Container（容器）** (`@container`) | 父容器宽度 |

### 容器查询用法

| 模式 | 类名 |
|------|------|
| 定义容器 | 在父元素上添加 `@container` |
| 容器断点 | 在子元素上使用 `@sm:`、`@md:`、`@lg:` |
| 命名容器 | `@container/card` 提升语义与精确性 |

### 何时使用

| 场景 | 选择 |
|------|------|
| 页面级布局 | 视口断点 |
| 组件级响应式 | 容器查询 |
| 可复用组件 | 容器查询（与上下文解耦） |

---

## 4. 响应式设计

### 断点系统

| 前缀 | 最小宽度 | 目标 |
|------|----------|------|
| (none) | 0px | Mobile-first 基础样式 |
| `sm:` | 640px | 大手机/小平板 |
| `md:` | 768px | 平板 |
| `lg:` | 1024px | 笔记本 |
| `xl:` | 1280px | 桌面端 |
| `2xl:` | 1536px | 大屏桌面 |

### Mobile-first 原则

1. 先写移动端基础样式（无前缀）
2. 再用前缀添加大屏覆盖规则
3. 示例：`w-full md:w-1/2 lg:w-1/3`

---

## 5. 深色模式

### 配置策略

| 方法 | 行为 | 适用场景 |
|------|------|----------|
| `class` | 通过 `.dark` 类切换 | 需要手动主题切换 |
| `media` | 跟随系统主题 | 不提供用户开关 |
| `selector` | 自定义选择器（v4） | 复杂多主题体系 |

### 深色模式示例

| 元素 | 浅色 | 深色 |
|------|------|------|
| Background | `bg-white` | `dark:bg-zinc-900` |
| Text | `text-zinc-900` | `dark:text-zinc-100` |
| Borders | `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 模式

| 模式 | 类名 |
|------|------|
| Auto-fit 响应式网格 | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
| 非对称（Bento） | `grid grid-cols-3 grid-rows-2` + spans |
| 侧栏布局 | `grid grid-cols-[auto_1fr]` |

> **说明：** 优先使用非对称/Bento（便当格）布局，避免千篇一律的对称三列网格。

---

## 7. 现代颜色系统

### OKLCH 与 RGB/HSL

| 格式 | 优势 |
|------|------|
| **OKLCH** | 感知均匀，更利于设计一致性 |
| **HSL** | 色相/饱和度语义直观 |
| **RGB** | 兼容性传统且广泛 |

### 颜色 Token 架构

| 层级 | 示例 | 作用 |
|------|------|------|
| **Primitive** | `--blue-500` | 原始色值层 |
| **Semantic** | `--color-primary` | 语义命名层 |
| **Component** | `--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 动效 | `hover:scale-105 transition-transform` |

---

## 10. 组件抽取

### 何时抽取

| 信号 | 动作 |
|------|------|
| 同一类组合出现 3 次以上 | 抽为组件 |
| 状态变体复杂 | 抽为组件 |
| 设计系统核心元素 | 抽取并补文档 |

### 抽取方式

| 方法 | 适用场景 |
|------|----------|
| **React/Vue component** | 需要动态逻辑或 JS 行为 |
| **@apply in CSS** | 静态样式、无需 JS |
| **Design tokens（设计令牌）** | 复用基础值（颜色/间距/字号） |

---

## 11. 反模式

| [FAIL]  不要这样做 | [OK]  推荐做法 |
|-------------|------------|
| 到处用任意值（arbitrary values） | 使用设计系统刻度 |
| 滥用 `!important` | 正确处理样式优先级 |
| 内联 `style=` | 优先使用 utilities |
| 重复超长 class 列表 | 抽取组件 |
| v3/v4 配置混用 | 完整迁移到 CSS-first |
| 重度使用 `@apply` | 优先组件化抽象 |

---

## 12. 性能原则

| 原则 | 实现方式 |
|------|----------|
| **清理未使用样式** | v4 默认自动处理 |
| **避免动态 class 拼接** | 不要用模板字符串生成类名 |
| **使用 Oxide** | v4 默认启用，速度更快 |
| **构建缓存** | 在 CI/CD 中启用缓存 |

---

> **牢记：** Tailwind v4 是 CSS-first。应充分使用 CSS Variables、Container Queries 与原生能力。配置文件已是可选项。