Tailwind CSS

Tailwind CSS是一个工具优先CSS（utility-first CSS）框架。一个 工具类（utility class） 通常只表达一小组声明，例如grid、p-6或text-slate-900；组件的最终外观来自这些类的组合。Tailwind在构建期生成普通CSS，浏览器里没有必须随应用运行的Tailwind样式引擎。

传统组件样式往往要求你先创造.product-card之类的名称，再去另一个文件维护声明。Tailwind把已有的设计词汇放到使用它的标记旁边，减少一次性类名和跨文件查找。它仍然依赖CSS的继承、层叠和媒体查询，所以工具类不是独立于CSS的另一套布局系统。

工具优先方法最适合有限且共享的设计系统：间距、颜色、字号、圆角和断点来自同一套令牌，组件只选择允许的组合。重复的是类名文本，而不是生成后的规则；相同候选类通常只对应一条CSS规则。需要复杂选择器、内容驱动样式或第三方组件覆盖时，普通CSS仍然是正确工具。

你会在HTML模板、React或Vue组件以及服务端模板中遇到Tailwind类名。框架不会理解这些文件的编程语言，它把源码当作文本寻找可能的类名，再尝试为有效候选项生成规则。这个约束解释了Tailwind最常见的生产故障：开发者或模型在运行时拼出一个从未以完整形式出现在源码里的类名。

本页针对Tailwind CSS 4.3.3。旧教程中的npx tailwindcss init、content数组和三个@tailwind指令描述的是早期主流程，不能直接当作v4的默认安装方式。迁移旧项目时应先确认实际主版本，再选择对应文档。

Tailwind的核心是“候选类名到CSS规则”的构建流程。构建工具加载主题和指令，源码检测器收集候选文本，编译器丢弃无法识别的候选项，并为其余项目生成规则。最终浏览器只接收CSS，不需要知道这些规则由Tailwind生成。

从候选类名到规则

一次构建可以按下面的顺序理解：

1. CSS入口导入Tailwind，并声明项目需要的主题变量或自定义规则。
2. 源码检测器从模板与组件中收集看起来可能是类名的文本。
3. 编译器把md:hover:bg-indigo-700拆成工具与条件变体。
4. 主题命名空间为颜色、间距、断点或圆角工具提供值。
5. 构建输出进入普通CSS层叠，由浏览器匹配元素与当前状态。

源码检测（source detection） 不是JavaScript求值，也不是AST类型检查。检测器可以看见字符串字面量bg-red-600，却不能推导`bg-${tone}-600`的可能结果。候选项只有在检测阶段可见，或通过@source明确注册，才有机会生成规则。

工具、变体与任意值

一个候选类名通常由可选 变体（variant） 、工具名和修饰值组成。hover:bg-indigo-700表示仅在悬停条件成立时应用背景色工具；md:grid-cols-2把网格列数工具包在最小宽度媒体查询中。变体可以堆叠，但每一段仍须是编译器识别的完整文本。

方括号中的任意值用于设计系统没有表达的真实例外，例如来自运行时CSS自定义属性的值。它们不是绕过令牌设计的快捷方式。大量近似颜色、像素宽度和复杂表达式会把隐含的设计系统分散到标记中，使审查与全局修改变难。

主题变量

主题变量（theme variable） 是在顶层@theme中声明的特殊CSS变量。它们既会成为生成CSS中的自定义属性，也会决定哪些工具存在；例如--color-brand-600可启用bg-brand-600等颜色工具，--radius-card可启用rounded-card。

普通:root自定义属性只有浏览器语义，不会单独创建Tailwind工具。需要一个令牌映射到工具API时用@theme；只需要运行时层叠值时用:root或组件作用域变量。两者可以结合，例如任意值工具读取var(--panel-opacity)。

主题变量让工具词汇与设计令牌保持联系，但命名仍是公共接口。删除或重命名变量可能让对应候选项不再生成。共享组件库应记录它要求的主题命名空间，并在使用方的生产构建中测试。

响应式与状态条件

Tailwind的响应式变体采用移动优先的最小宽度规则。无前缀工具是所有宽度的基线，md:从md断点开始覆盖，xl:再从更宽的范围覆盖。sm:不是“手机样式”，而是从默认主题的sm最小宽度开始生效的条件。

状态变体把伪类、媒体特性、属性或结构关系编码在候选项中。hover:、focus-visible:、disabled:、dark:、motion-reduce:、group-*与peer-*都是在条件满足时激活工具。它们只能改变视觉规则，不能为div补出按钮语义、键盘行为或可访问名称。

响应式规则也不应代替内容顺序设计。order-*、Grid定位或隐藏工具可以改变视觉结果，却不会自动产生正确的DOM、阅读和焦点顺序。每个断点都应使用真实内容、键盘操作和文本缩放验证。

源码边界与组件边界

Tailwind v4默认自动检测项目源码，同时忽略.gitignore文件、依赖目录、二进制文件、CSS文件和常见锁文件。Monorepo或外部组件包中的类可能落在自动边界之外，可以用相对于样式表的@source注册路径。source(none)适合需要完全显式控制多个样式入口的项目。

动态状态应映射到完整的静态类名。组件可以维护toneClasses = { danger: 'bg-red-600', safe: 'bg-green-600' }，再按属性选择映射值。这样检测器能看见候选项，代码审查也能看到允许的有限状态。

重复标记优先通过框架组件或模板局部封装，因为这会同时保存结构、行为和样式契约。@apply可以把现有工具内联进自定义CSS，但它会重新引入命名与样式表边界，不应只为缩短一处class属性而使用。复杂选择器或真正共享的第三方覆盖直接写CSS往往更清楚。

下面四个夹具使用本地Tailwind CSS 4.3.3编译器执行。@source inline()只负责让隔离文件的候选项确定可见；真实应用通常从HTML或组件源码自动检测这些完整类名。输出保留编译器生成的版本横幅，并且没有手工改写。

组合基础工具

第一个夹具定义卡片需要的最小主题，并请求六个完整候选项。它展示了工具如何引用主题变量，而不是把间距和颜色复制到每个组件中。

标记中无论重复多少次p-6，这个夹具仍只需要一条.p-6规则。另一方面，主题里没有相应命名空间时，候选项可能无法生成；这就是令牌词汇与可用工具之间的契约。

编译交互状态

第二个夹具加入悬停、可见焦点和禁用状态。候选类名中的冒号会在选择器中转义，变体则成为媒体查询或伪类条件。

/* Each complete token can be detected without evaluating JavaScript. */
@theme {
  --spacing: 0.25rem;
  --color-indigo-600: oklch(51.1% 0.262 276.966);
  --color-indigo-700: oklch(45.7% 0.24 277.023);
  --color-white: #fff;
  --radius-lg: 0.5rem;
}

@source inline("rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700 focus-visible:outline-2 disabled:opacity-50");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
@layer properties;
:root, :host {
  --spacing: 0.25rem;
  --color-indigo-600: oklch(51.1% 0.262 276.966);
  --color-indigo-700: oklch(45.7% 0.24 277.023);
  --color-white: #fff;
  --radius-lg: 0.5rem;
}
.rounded-lg {
  border-radius: var(--radius-lg);
}
.bg-indigo-600 {
  background-color: var(--color-indigo-600);
}
.px-4 {
  padding-inline: calc(var(--spacing) * 4);
}
.py-2 {
  padding-block: calc(var(--spacing) * 2);
}
.text-white {
  color: var(--color-white);
}
@media (hover: hover) {
  .hover\:bg-indigo-700:hover {
    background-color: var(--color-indigo-700);
  }
}
.focus-visible\:outline-2:focus-visible {
  outline-style: var(--tw-outline-style);
  outline-width: 2px;
}
.disabled\:opacity-50:disabled {
  opacity: 50%;
}
@property --tw-outline-style {
  syntax: "*";
  inherits: false;
  initial-value: solid;
}
@layer properties {
  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
    *, ::before, ::after, ::backdrop {
      --tw-outline-style: solid;
    }
  }
}

编译结果没有为按钮添加disabled属性或键盘行为；这些仍由HTML与组件逻辑负责。悬停规则受@media (hover: hover)保护，也说明测试不能只模拟鼠标悬停。

建立移动优先网格

第三个夹具先生成单列基线，再在md与xl最小宽度上生成覆盖规则。源码里的--breakpoint-lg没有对应候选项，因此本次输出不包含lg媒体查询。

/* Unprefixed utilities are the mobile baseline. */
@theme {
  --spacing: 0.25rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
}

@source inline("grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-4");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
:root, :host {
  --spacing: 0.25rem;
}
.grid {
  display: grid;
}
.grid-cols-1 {
  grid-template-columns: repeat(1, minmax(0, 1fr));
}
.gap-4 {
  gap: calc(var(--spacing) * 4);
}
@media (width >= 48rem) {
  .md\:grid-cols-2 {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}
@media (width >= 80rem) {
  .xl\:grid-cols-4 {
    grid-template-columns: repeat(4, minmax(0, 1fr));
  }
}

把md:grid-cols-2误读为“仅在中等宽度”会产生错误测试。它从48rem开始持续生效，直到同属性的更宽条件或其他层叠规则覆盖它。

连接主题与运行时变量

最后一个夹具让@theme创建品牌色与圆角工具，同时保留普通:root变量作为运行时透明度输入。任意值工具引用变量，不需要为每个透明度生成新类。

/* Theme variables create utilities; ordinary variables do not. */
@theme {
  --spacing: 0.25rem;
  --color-brand-600: oklch(52% 0.2 255);
  --radius-card: 0.75rem;
}

:root {
  --panel-opacity: 0.92;
}

@source inline("rounded-card bg-brand-600 p-6 opacity-[var(--panel-opacity)]");
@tailwind utilities;

/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
:root, :host {
  --spacing: 0.25rem;
  --color-brand-600: oklch(52% 0.2 255);
  --radius-card: 0.75rem;
}
:root {
  --panel-opacity: 0.92;
}
.rounded-card {
  border-radius: var(--radius-card);
}
.bg-brand-600 {
  background-color: var(--color-brand-600);
}
.p-6 {
  padding: calc(var(--spacing) * 6);
}
.opacity-\[var\(--panel-opacity\)\] {
  opacity: var(--panel-opacity);
}

如果透明度随元素实例变化，组件可设置--panel-opacity，候选类名保持静态。这个边界避免产生无限的opacity-[0.913]一次性候选项，也让运行时值继续参与CSS层叠。

在运行时拼接类名

修复： 把有限输入映射到完整字符串，例如{ danger: 'bg-red-600', safe: 'bg-green-600' }。必须引入检测边界外的类时，精确注册源码路径或使用范围尽可能小的@source inline()，不要用宽泛保留列表掩盖未知状态。

把断点前缀当作设备名称

修复： 先写无前缀基线，再从内容真正需要变化的位置添加覆盖。测试断点前后各一个CSS像素，并加入长文本、缩放文字和真实容器宽度。

用视觉工具替代语义和焦点

修复： 操作用原生button，导航用带href的链接，并明确type。只有提供经验证的focus-visible替代样式后才移除默认轮廓，同时用键盘和高对比模式检查。

依赖class属性中的先后顺序

修复： 每个状态只发出一个负责同一属性的工具。若组件允许调用方覆盖样式，应定义明确的合并契约并测试最终计算样式，而不是靠重排字符串修复冲突。

让任意值吞掉设计系统

修复： 真正重复或具有产品含义的值提升为@theme令牌；高基数运行时值通过普通CSS自定义属性传入。代码审查中统计新增任意值，并要求每个例外说明约束来源。

把v3配置复制到v4项目

修复： 先从锁文件确认主版本。v4的Vite集成安装tailwindcss与@tailwindcss/vite、注册插件，并在CSS中使用@import "tailwindcss"；旧项目迁移则按官方升级说明逐项处理。

• Tailwind CSS：使用Vite安装
• Tailwind CSS：使用工具类设计样式
• Tailwind CSS：检测源码中的类名
• Tailwind CSS：主题变量
• Tailwind CSS：悬停、焦点与其他状态
• Tailwind CSS：响应式设计