Tailwind CSS 速通：有 CSS 基础的实战入门

文章目录

[Tailwind CSS 速通：有 CSS 基础的实战入门](#Tailwind CSS 速通：有 CSS 基础的实战入门)
- [一、Tailwind CSS 是什么，以及为什么 AI 时代更重要](#一、Tailwind CSS 是什么，以及为什么 AI 时代更重要)
- [二、Tailwind CSS 的版本与 v4 配置思路](#二、Tailwind CSS 的版本与 v4 配置思路)
- - [1. v4：配置思路变了](#1. v4：配置思路变了)
  - [2. 理解 `@theme`](#2. 理解 @theme)
- [三、Tailwind CSS 常用语法速览](#三、Tailwind CSS 常用语法速览)
- - [1. 语法的基本形式](#1. 语法的基本形式)
  - [2. 布局：Flex 与 Grid](#2. 布局：Flex 与 Grid)
  - [3. 间距：Margin、Padding、Gap](#3. 间距：Margin、Padding、Gap)
  - [4. 宽高与容器](#4. 宽高与容器)
  - [5. 文字与颜色](#5. 文字与颜色)
  - [6. 边框、圆角、阴影](#6. 边框、圆角、阴影)
  - [7. 定位](#7. 定位)
  - [8. 状态：前缀 + 原 class](#8. 状态：前缀 + 原 class)
  - [9. 响应式：前缀 + 原 class](#9. 响应式：前缀 + 原 class)
  - [10. 一个完整例子：从 CSS 翻译到 Tailwind](#10. 一个完整例子：从 CSS 翻译到 Tailwind)
- [四、Tailwind CSS 的项目使用规则](#四、Tailwind CSS 的项目使用规则)
- - [1. 什么时候使用 Tailwind CSS，什么时候使用原生 CSS？](#1. 什么时候使用 Tailwind CSS，什么时候使用原生 CSS？)
  - [2. 建议的项目约定](#2. 建议的项目约定)
  - [3. Tailwind CSS 工作流示例](#3. Tailwind CSS 工作流示例)

Tailwind CSS 速通：有 CSS 基础的实战入门

本文速览

一句话总结：

本文从传统 CSS 的写法切入，快速梳理 Tailwind CSS 的 utility-first 思路、v4 的 @theme 配置、常用语法，以及它与原生 CSS 的使用边界。

适合人群：

已有 CSS 基础，想快速上手 Tailwind CSS，或需要在 AI 辅助开发中更高效编写和审查界面样式的前端开发者。

核心问题：

Tailwind CSS 与传统 CSS 的写法有什么不同？
为什么 Tailwind 的结构化 utility class 更适合 AI 协作？
Tailwind v3 与 v4 的配置思路有什么差异？
@theme 如何把设计 token 转换为可用 utility？
什么场景应使用 Tailwind，什么场景应保留原生 CSS？

你将学会：

用 Tailwind class 表达布局、间距、排版、状态和响应式样式；
理解 v4 中以 CSS 为中心的 token 配置方式；
读懂 @theme、CSS 变量与 Tailwind utility 之间的关系；
按项目场景选择 utility、组件与自定义 CSS；
建立一套可维护的 Tailwind 编写顺序与审查要点。

相关关键词：

Tailwind CSS、utility-first、CSS、AI 辅助开发、Tailwind v4、@theme、CSS 变量、响应式设计、设计 token、原生 CSS

一、Tailwind CSS 是什么，以及为什么 AI 时代更重要

Tailwind CSS 是一种"工具类优先"的 CSS 框架。传统写法是先给元素起语义类名，再去 CSS 文件里写一组样式：

html 复制代码

<button class="primary-button">保存</button>

css 复制代码

.primary-button {
  padding: 8px 16px;
  border-radius: 8px;
  background: #2563eb;
  color: white;
}

Tailwind 则把这些 CSS 声明直接写成可组合的 utility class：

html 复制代码

<button class="rounded-lg bg-blue-600 px-4 py-2 text-white">
  保存
</button>

AI 擅长处理有明确模式、组合规则稳定的语言。Tailwind 恰好把 UI 样式压缩成了一套结构化词汇：

text 复制代码

"一个移动端单列、桌面三列、悬浮有阴影的卡片区"
→ grid grid-cols-1 gap-4 md:grid-cols-3 hover:shadow-md

这带来几个实际优势：

生成更直接：AI 能把设计意图直接变成 class，不必先判断 CSS 写在哪个文件、该起什么类名、如何避免全局冲突。
修改更局部：让 AI"把卡片间距从 16 改为 24"，它通常只改 gap-4 为 gap-6，影响范围清楚。
更容易审查：熟悉常用类后，你可以直接读出布局、间距、响应式和状态，不必跨 JSX 与 CSS 文件来回找。
更利于保持一致：p-4、gap-6、rounded-xl 这些 token 会自然约束 AI 不要随手写各种 17px、19px。

二、Tailwind CSS 的版本与 v4 配置思路

Tailwind 的迭代主线很清晰：从"提供很多工具类"，走到了"按需生成、配置更少、CSS 原生能力更强"。

版本	时间	关键变化	对你意味着什么
v1	2019	第一个稳定版，确立 utility-first 思路	历史了解即可
v2	2020	新色板、暗色模式、`2xl`、更多状态变体；`@apply` 能配合响应式/状态使用	很多旧教程从这代开始
v2.1	2021	引入 JIT（按代码中实际 class 即时生成 CSS）	任意值 `w-[123px]` 这类能力开始变得实用
v3	2021	JIT 成为默认；任意值、内容扫描、任意变体等成为标准工作流	目前大量存量项目、教程和组件代码仍是 v3 写法
v4	2025	新构建引擎、CSS-first 配置、原生 CSS 能力、接入更轻	新项目建议以它为主
v4.3	2026	当前版本，补充了 scrollbar、逻辑属性、zoom、tab-size 等 utility	学核心理念即可，无须追逐新增小功能

1. v4：配置思路变了

v4 最值得你关注的不是新增几个 class，而是从 JavaScript 配置优先转向 CSS 配置优先。

v3 常见写法：

javascript 复制代码

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#2563eb",
      },
    },
  },
}

v4 新项目推荐：

css 复制代码

@import "tailwindcss";

@theme {
  --color-brand-500: #2563eb;
}

然后同样使用：

html 复制代码

<button class="bg-brand-500">保存</button>

也就是说，设计 token 现在天然就是 CSS 变量，同时还能生成 Tailwind utility。v4 还带来更高性能的引擎、简化安装和官方 Vite 插件。

简单理解为：

text 复制代码

Tailwind v3：主要在 tailwind.config.js 里配 token
Tailwind v4：主要在 CSS 的 @theme 里配 token

2. 理解 `@theme`

@theme 是 Tailwind CSS 的特殊配置。

@theme 不会原样交给浏览器；Tailwind 会先把它"编译"成浏览器认识的 CSS 变量。

css 复制代码

@import "tailwindcss";

@theme {
  --radius-card: 12px;
}

经过 Tailwind 编译后，浏览器拿到的最终 CSS，大致会包含：

css 复制代码

:root {
  --radius-card: 12px;
}

这一步就叫"输出 CSS 变量"。

然后浏览器才可以在任何 CSS 规则中读取它：

css 复制代码

.card {
  border-radius: var(--radius-card);
}

:root 是 CSS 里网页最顶层元素 <html> 的选择器。把变量定义在这里，通常全页面都能继承和使用，所以它常被用来放"全局 CSS 变量"。

Tailwind 对 @theme 里的变量前缀有一张"翻译规则表"。

你写：

css 复制代码

@theme {
  --radius-card: 12px;
}

Tailwind 看到 --radius- 这个前缀，就知道：

这是一个"圆角 token"，请生成名为 rounded-card 的 utility。

所以：

html 复制代码

<div class="rounded-card"></div>

最终大致生成：

css 复制代码

.rounded-card {
  border-radius: var(--radius-card);
}

重点：不是所有 CSS 变量都能被 Tailwind CSS 翻译；必须同时满足以下条件：

写在 @theme {} 里面；
使用 Tailwind 规定的命名空间，例如 --color-*、--radius-*、--font-*、--shadow-*。

三、Tailwind CSS 常用语法速览

Tailwind CSS 把常用 CSS 声明预先做成许多小 class（utility）。你在 HTML/JSX 的 class / className 中组合这些 class 来写样式。

css 复制代码

/* 传统 CSS：先命名，再去 CSS 文件写样式 */
.card {
  display: flex;
  gap: 16px;
  padding: 24px;
  border-radius: 12px;
}

html 复制代码

<!-- Tailwind：直接把同样的样式写在元素上 -->
<div class="flex gap-4 p-6 rounded-xl"></div>

读法：一个 Tailwind class，通常就是一条或一组很小的 CSS 声明。

1. 语法的基本形式

text 复制代码

[条件:]功能-值

html 复制代码

<button class="md:hover:bg-blue-700">保存</button>

bg：功能，background-color。
blue-700：值，蓝色 token。
hover:：条件，鼠标悬浮时。
md:：条件，中屏及以上。

它等价于大致这样的 CSS：

css 复制代码

@media (width >= 48rem) {
  button:hover { background-color: /* blue-700 */; }
}

2. 布局：Flex 与 Grid

css 复制代码

/* CSS */
.row {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: space-between;
}

html 复制代码

<!-- Tailwind -->
<div class="flex flex-col items-center justify-between"></div>

CSS	Tailwind
`display: flex`	`flex`
`flex-direction: column`	`flex-col`
`flex-direction: row`	`flex-row`（默认）
`align-items: center`	`items-center`
`justify-content: center`	`justify-center`
`justify-content: space-between`	`justify-between`
`display: grid`	`grid`
`grid-template-columns: repeat(3, minmax(0, 1fr))`	`grid-cols-3`

html 复制代码

<!-- 默认一列，md 屏幕起三列 -->
<div class="grid grid-cols-1 gap-4 md:grid-cols-3"></div>

3. 间距：Margin、Padding、Gap

css 复制代码

/* CSS */
.box {
  margin: 16px;
  padding: 24px;
  gap: 16px;
}

html 复制代码

<!-- Tailwind -->
<div class="m-4 p-6 gap-4"></div>

CSS 属性	Tailwind 模板	例子
`padding`	`p-{值}`	`p-4`
左右 `padding`	`px-{值}`	`px-4`
上下 `padding`	`py-{值}`	`py-2`
上 `margin`	`mt-{值}`	`mt-6`
`margin`	`m-{值}`	`m-4`
子元素间距	`gap-{值}`	`gap-4`
垂直子元素间距	`space-y-{值}`	`space-y-3`

高频值：1=4px、2=8px、3=12px、4=16px、6=24px、8=32px。

4. 宽高与容器

css 复制代码

/* CSS */
.page { width: 100%; max-width: 1280px; margin-inline: auto; }
.avatar { width: 40px; height: 40px; object-fit: cover; }

html 复制代码

<!-- Tailwind -->
<main class="mx-auto w-full max-w-7xl"></main>
<img class="h-10 w-10 object-cover" />

CSS	Tailwind
`width: 100%`	`w-full`
`width: 50%`	`w-1/2`
`height: 100%`	`h-full`
`max-width: ...`	`max-w-*`
水平 `margin: auto`	`mx-auto`
`min-height: 100vh`	`min-h-screen`

5. 文字与颜色

css 复制代码

/* CSS */
h1 { font-size: 30px; font-weight: 700; color: #0f172a; }
p { font-size: 14px; line-height: 24px; color: #475569; }

html 复制代码

<!-- Tailwind -->
<h1 class="text-3xl font-bold text-slate-900">标题</h1>
<p class="text-sm leading-6 text-slate-600">说明</p>

CSS 属性	Tailwind 模板	例子
`font-size`	`text-{大小}`	`text-sm`、`text-xl`
`font-weight`	`font-{粗细}`	`font-medium`、`font-bold`
`line-height`	`leading-{值}`	`leading-6`
`color`	`text-{颜色}-{深浅}`	`text-slate-900`
`background-color`	`bg-{颜色}-{深浅}`	`bg-blue-600`

6. 边框、圆角、阴影

css 复制代码

/* CSS */
.card {
  border: 1px solid #e2e8f0;
  border-radius: 12px;
  background: white;
  box-shadow: ...;
}

html 复制代码

<!-- Tailwind -->
<section class="rounded-xl border border-slate-200 bg-white shadow-sm"></section>

CSS 属性	Tailwind
`border: 1px solid ...`	`border border-slate-200`
`border-radius`	`rounded-md` / `rounded-lg` / `rounded-xl` / `rounded-full`
`box-shadow`	`shadow-sm` / `shadow-md` / `shadow-lg`

7. 定位

css 复制代码

/* CSS */
.parent { position: relative; }
.badge { position: absolute; top: 8px; right: 8px; z-index: 10; }

html 复制代码

<!-- Tailwind -->
<div class="relative">
  <span class="absolute right-2 top-2 z-10"></span>
</div>

CSS	Tailwind
`position: relative`	`relative`
`position: absolute`	`absolute`
`top: 8px`	`top-2`
`right: 8px`	`right-2`
`z-index: 10`	`z-10`
`position: fixed; inset: 0`	`fixed inset-0`

8. 状态：前缀 + 原 class

css 复制代码

/* CSS */
.button:hover { background: #1d4ed8; }
.button:disabled { opacity: .5; }

html 复制代码

<!-- Tailwind -->
<button class="bg-blue-600 hover:bg-blue-700 disabled:opacity-50">
  保存
</button>

CSS 选择器	Tailwind 前缀
`:hover`	`hover:`
`:focus-visible`	`focus-visible:`
`:active`	`active:`
`:disabled`	`disabled:`

9. 响应式：前缀 + 原 class

css 复制代码

/* CSS：中等屏及以上 */
@media (min-width: 768px) {
  .box { padding: 32px; font-size: 18px; }
}

html 复制代码

<!-- Tailwind -->
<div class="px-4 text-base md:px-8 md:text-lg"></div>

不带前缀是移动端默认；sm:、md:、lg: 表示对应宽度及以上覆盖。

10. 一个完整例子：从 CSS 翻译到 Tailwind

css 复制代码

.card {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 24px;
  border: 1px solid #e2e8f0;
  border-radius: 12px;
  background: white;
}

@media (min-width: 768px) {
  .card { flex-direction: row; }
}

html 复制代码

<article class="flex flex-col gap-4 rounded-xl border border-slate-200 bg-white p-6 md:flex-row">
  ...
</article>

读这一行的顺序：布局 flex flex-col → 间距 gap-4 p-6 → 外观 rounded-xl border ... bg-white → 响应式 md:flex-row。

四、Tailwind CSS 的项目使用规则

1. 什么时候使用 Tailwind CSS，什么时候使用原生 CSS？

场景	建议
页面一次性的布局、间距、文字、栅格	Tailwind 直接写
只出现一次的小卡片/区块	Tailwind 直接写
同一 UI 模式出现 2--3 次	抽成组件，组件内部继续用 Tailwind
富文本内容（文章 `h1/p/ul`）	CSS / `@apply` 更合适
很复杂的动画、伪元素、难表达的选择器	CSS 更合适
第三方组件覆盖	CSS 更合适
多个页面共享的品牌变量、主题 token	Tailwind theme / CSS variables
大量像素级、绝对定位的视觉还原	可混用 CSS；不要强迫 Tailwind

2. 建议的项目约定

新项目用 Tailwind v4 的 CSS-first 配置；少量全局 token；组件内直接写 utility；默认不用 @apply。

3. Tailwind CSS 工作流示例

markdown 复制代码

---
name: tailwindcss-workflow
description: 构建、迁移、审查并规范 Tailwind CSS v4+ 界面。需要用 Tailwind 实现 UI、将页面或组件 CSS 迁移至 Tailwind、定义 Tailwind 设计 token 与 CSS-first 配置、判断 Tailwind/自定义 CSS/@apply 的使用边界，或审查 Tailwind 代码的可维护性与无障碍性时使用。
---

# Tailwind CSS 工作流

## 默认决策

- 新项目以 Tailwind CSS v4+ 为目标。修改已有项目之前先检查已安装版本；已使用 v3 的项目遵循其 v3 配置方式。
- 常规页面和组件样式使用 utility class。
- 复杂选择器/伪元素、内部结构不可控的富文本、第三方 DOM 覆盖、复杂动画使用自定义 CSS。
- 原生 CSS 直接书写；默认不使用 `@apply` 或 `@layer`。只有项目已有明确约定或确实能显著减少复杂选择器重复时，才使用它们。
- 优先使用 Tailwind 默认 token。任意值仅用于精确设计约束或计算；重复出现的任意值应提升为项目 token。
- 使用语义化 HTML、移动端优先的响应式写法，以及键盘可见的焦点状态。

## 工作流

### 1. 修改前先检查

1. 阅读包管理清单和现有全局 CSS。
2. 确认 Tailwind 版本、构建集成方式、现有 token 来源、格式化/检查规则和组件约定。
3. 除非任务明确包含版本或配置迁移，否则保持项目已有约定。

### 2. 选择样式实现边界

| 场景 | 首选方式 |
|---|---|
| 一次性的页面布局或组件样式 | 在标记中直接写 Tailwind utility |
| 重复且有明确业务语义的 UI 模式 | 抽为语义组件，组件内部使用 Tailwind |
| 富文本 / Markdown / CMS HTML | 作用域明确的自定义 CSS |
| 第三方 DOM 或需要复杂选择器的覆盖 | 作用域明确的自定义 CSS |
| 复杂动画或大量伪元素效果 | 自定义 CSS，并复用主题变量 |
| 一次性的精确计算或设计值 | 任意值，例如 `top-[calc(100%+6px)]` |

不要仅为了缩短 utility 列表而抽取 CSS class。当 UI 有明确名称、重复使用或存在有意义的变体时，才抽取组件。

### 3. 以一致顺序书写 utility

按以下顺序书写 utility：

1. 布局与定位（`flex`、`grid`、`relative`、`z-*`）
2. 尺寸与间距（`w-*`、`p-*`、`gap-*`）
3. 视觉外观（`border`、`rounded-*`、`bg-*`、`shadow-*`）
4. 排版（`text-*`、`font-*`、`leading-*`）
5. 交互与状态（`transition-*`、`hover:*`、`focus-visible:*`、`disabled:*`）
6. 响应式/主题变体（`sm:*`、`md:*`、`lg:*`、`dark:*`）

使用移动端优先的基础样式。仅在更大屏幕需要增强时加入 `sm:` / `md:` / `lg:`。

```tsx
<button className="inline-flex items-center justify-center gap-2 rounded-lg bg-brand-500 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-brand-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand-500 disabled:pointer-events-none disabled:opacity-50">
  保存
</button>
```

条件 class 使用项目已有工具（`cn`、`clsx` 或同类工具）和完整的 class 映射。不要动态拼接 class 名，例如 `bg-${color}-500`。

```tsx
const toneClass = {
  success: "bg-emerald-600 hover:bg-emerald-700",
  danger: "bg-red-600 hover:bg-red-700",
} as const;
```

### 4. 在 v4 中配置 token

将共享设计 token 放入全局 Tailwind CSS 入口文件。只添加真正代表全项目设计决策的 token。

```css
@import "tailwindcss";

@theme {
  --font-sans: "Inter", "PingFang SC", sans-serif;
  --color-brand-500: oklch(0.58 0.2 260);
  --color-brand-600: oklch(0.5 0.2 260);
  --radius-card: 0.75rem;
  --shadow-card: 0 8px 24px rgb(15 23 42 / 0.08);
}
```

这会生成 `bg-brand-500`、`font-sans`、`rounded-card`、`shadow-card` 等项目 utility。需要生成 utility 的 token 使用 `@theme`；不需要生成 utility 的普通 CSS 变量使用 `:root`。

没有明确的全项目设计系统要求时，不要清空默认主题，也不要重定义整套间距尺度。

### 5. 有意识地使用任意值

常规间距、文字、颜色、圆角和阴影优先使用 token：

```tsx
<div className="rounded-xl p-4 text-sm" />
```

精确规格或计算值允许使用任意值：

```tsx
<div className="grid-cols-[240px_1fr] top-[calc(100%+6px)] w-[372px]" />
```

同一个任意值出现在两个或更多独立维护的位置时，建议改为有名称的 `@theme` token 或语义组件。

### 6. 直接书写必要的原生 CSS

当 Tailwind 不适合表达时，直接在对应的 CSS 文件中书写原生 CSS。保持选择器作用域明确，并使用同一套设计 token：

```css
.article-content h2 {
  margin-top: 2rem;
  color: var(--color-slate-900);
  font-size: var(--text-xl);
  font-weight: var(--font-weight-semibold);
}
```

不要仅为了隐藏一串 utility 而引入 `.primary-button` 这类全局别名。可复用 UI 应优先抽为 `Button` 组件。`@apply` 和 `@layer` 是可选工具，不是日常组件样式的默认方案。

## CSS 迁移至 Tailwind 的步骤

1. 除非任务要求调整结构，否则保持行为和 DOM 结构不变。
2. 先迁移布局：容器、Flex/Grid、间距和尺寸。
3. 再迁移视觉外观：颜色、排版、边框、圆角和阴影。
4. 最后补齐响应式和交互状态。
5. 在上述边界下仍然更清晰的部分保留 CSS。
6. 检查导入和受影响页面后，再删除废弃 CSS。
7. 运行仓库已有的格式化、类型检查、lint 和测试命令；在移动端与桌面端宽度下目视检查改动页面。

## 审查清单

- 使用语义化原生控件和标签。
- 交互控件包含 `focus-visible` 样式；在适用时处理 disabled/loading 状态。
- 避免不必要的任意值、`!important` 和大量绝对定位。
- 避免动态拼接 class 名。
- 重复 UI 放入语义组件；一次性样式保持局部。
- CSS 迁移后验证响应式行为和视觉一致性。

结论：Tailwind CSS 的核心不是记住所有 class，而是用稳定的 utility 词汇表达布局、间距、外观和状态。新项目可优先采用 v4 的 CSS-first 配置；常规组件使用 utility，复杂选择器、富文本和第三方 DOM 覆盖则保留清晰、作用域明确的原生 CSS。

Tailwind CSS 速通：有 CSS 基础的实战入门

文章目录