tailwind-css

Tailwind CSS（v4）

概述

Tailwind CSS 是一个实用优先的 CSS 框架。通过在标记中组合单一用途的类来设置样式。

我们仅使用 Tailwind v4。 不存在 tailwind.config.js、tailwind.config.ts 或 tailwind.config.mjs。通过 CSS 中的 @import "tailwindcss" 和 @theme 指令，以及 Vite 或 PostCSS 插件进行配置。

• 入口：一个包含 @import "tailwindcss"; 的主 CSS 文件
• 构建：@tailwindcss/vite（Vite）或 @tailwindcss/postcss（Next.js）
• 主题：在同一个 CSS 文件（或导入的 CSS 文件）中使用 @theme { ... }。不使用 JS 配置。

核心原则：优先在标记中使用实用类；需要时通过 @theme 和自定义 CSS 扩展。切勿建议或创建 tailwind.config.* 或配置文件中的 content/theme。

---

安装

Next.js（App Router，15+）

1. 创建项目（如有需要）：create-next-app@latest — 参阅 Next.js 文档。
2. 添加软件包：tailwindcss、@tailwindcss/postcss、postcss（使用你的软件包管理器）。
3. 在项目根目录创建 postcss.config.mjs：

const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
export default config;

4. 在 ./app/globals.css 中：

@import "tailwindcss";

5. 运行开发脚本（例如 package.json 中的 dev）。

在 React/TSX 中使用 className（例如在 app/page.tsx 中）：

export default function Home() {
  return (
    <h1 className="text-3xl font-bold underline">
      Hello world!
    </h1>
  );
}

确保在 app/layout.tsx 中导入 app/globals.css（Create Next App 默认会执行此操作）。

Vite（React、Vue、Qwik 等）

1. 添加软件包：tailwindcss、@tailwindcss/vite（使用你的软件包管理器）。
2. 在 vite.config.ts 中：

import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss(), /* ... */],
})

3. 主 CSS 文件（例如 src/index.css）：@import "tailwindcss";

Tailwind CLI（独立使用）

1. 添加软件包：tailwindcss、@tailwindcss/cli（使用你的软件包管理器）。
2. 主 CSS 文件：@import "tailwindcss";
3. 构建：@tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch（通过软件包管理器调用）。

---

使用 Tailwind

• 在标记中使用实用类：在 React/Next.js 中使用 className，在 Qwik/Vue 中使用 class。
• 尽可能优先使用设计令牌（主题），而不是任意值。
• 将相关实用类分组以提高可读性（布局 → 间距 → 排版 → 颜色 → 效果）。

示例：text-3xl font-bold underline、flex items-center gap-4、p-6 rounded-xl bg-white shadow-lg、max-w-sm mx-auto。

---

主题：仅使用 @theme（不使用配置文件）

仅在 CSS 中使用。 在与 @import "tailwindcss" 相同的文件中使用 @theme（或在由该文件导入的 CSS 中使用）。

扩展默认主题

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

使用方式：font-display、3xl:、bg-avocado-500、ease-fluid。

覆盖默认值

在 @theme 中重新定义变量即可覆盖默认值：

@theme {
  --breakpoint-sm: 30rem;
}

主题变量命名空间（快速参考）

命名空间	用途	示例
--color-*	颜色	bg-*, text-*, border-*
--font-*	字体系列	font-sans、font-mono
--text-*	字号	text-xl、text-base
--font-weight-*	字重	font-bold
--breakpoint-*	响应式变体	sm:、md:、lg:
--spacing-*	间距/尺寸	p-4、gap-2、m-6
--radius-*	边框圆角	rounded-lg
--shadow-*	盒阴影	shadow-md
--ease-*	过渡时序	ease-out
--animate-*	动画	animate-spin

引用其他变量

当令牌需要引用另一个变量时，使用 @theme inline：

@theme inline {
  --font-sans: var(--font-inter);
}

自定义关键帧

在 @theme 中定义关键帧，使其可供 --animate-* 使用：

@theme {
  --animate-fade-in-scale: fade-in-scale 0.3s ease-out;
  @keyframes fade-in-scale {
    0% { opacity: 0; transform: scale(0.95); }
    100% { opacity: 1; transform: scale(1); }
  }
}

如需了解更多主题选项（覆盖整个命名空间、自定义主题、在项目间共享），请参阅 reference.md。

---

自定义样式

纯 CSS

在包含 @import "tailwindcss" 的同一文件中添加自定义 CSS，也可以添加到导入的文件中：

@import "tailwindcss";

.my-custom-style {
  /* ... */
}

基础层

使用 @layer base 设置元素默认样式：

@layer base {
  h1 { font-size: var(--text-2xl); }
  h2 { font-size: var(--text-xl); }
}

组件层

使用 @layer components 编写可复用的类组件类（必要时使用工具类覆盖）：

@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-lg);
    padding: var(--spacing-6);
    box-shadow: var(--shadow-xl);
  }
}

自定义工具类：@utility

简单工具类：

@utility content-auto {
  content-visibility: auto;
}

复杂工具类（例如隐藏滚动条）：

@utility scrollbar-hidden {
  &::-webkit-scrollbar {
    display: none;
  }
}

自定义变体：@variant

在自定义 CSS 中使用 @variant：

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

或者使用 @custom-variant 注册具名变体：

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

然后使用：theme-midnight:bg-black。

---

任意值和属性

• 任意值：top-[117px]、bg-[#bada55]、text-[22px]、lg:top-[344px]。
• 任意值中的 CSS 变量：fill-(--my-brand-color)（fill-[var(--my-brand-color)] 的简写形式）。
• 任意属性：[mask-type:luminance]、[--scroll-offset:56px]。
• 值中的空格：使用下划线 _ 表示空格，例如 grid-cols-[1fr_500px_2fr]。
• 歧义：使用类型提示：text-(length:--my-var) 和 text-(color:--my-var)。

---

兼容性

• 浏览器：Tailwind v4 面向现代浏览器（Chrome 111+、Safari 16.4+、Firefox 128+）。部分工具类使用了较新的特性；如果需要支持旧版浏览器，请避免使用这些工具类。
• 预处理器：不要在同一流水线中将 Tailwind 与 Sass/Less/Stylus 搭配使用；请将 Tailwind 用作主要样式层。

---

快速参考

任务	操作
入口	一个包含 @import "tailwindcss"; 的 CSS 文件
Next.js	在 postcss.config.mjs 中使用 @tailwindcss/postcss，无需 Tailwind 配置文件
Vite	使用来自 @tailwindcss/vite 的 tailwindcss()
主题	仅在 CSS 中使用 @theme { ... }
基础样式	@layer base { ... }
组件	@layer components { ... }
自定义工具类	@utility name { ... }
自定义变体	@custom-variant name (selector);

---

常见错误

• 属性错误：React/Next 使用 className；Qwik/Vue 使用 class。
• 缺少导入：包含 @import "tailwindcss" 的文件必须由应用加载（例如在根布局中加载）。
• 配置文件：不要创建或建议使用 tailwind.config.js、tailwind.config.ts 或任何 tailwind.config.* 文件。不要建议在 JS 配置中使用 content: []、theme: {} 或插件。Tailwind v4 仅使用 CSS（@import "tailwindcss" + @theme）以及 Vite/PostCSS 插件。

---

其他资源

• reference.md — 主题选项、官方文档链接、默认主题摘要。
• 官方：Tailwind CSS v4 文档 — 安装、主题、添加自定义样式、兼容性。