tailwind-css

用途

Tailwind CSS 是一个实用优先（utility-first）的 CSS 框架，通过扫描 HTML 文件、JavaScript 组件和模板中的类名来生成 CSS。它提供单一用途的工具类，可直接在标记中组合使用，从而无需编写自定义 CSS 即可快速开发 UI。

核心原则

实用优先样式：通过在标记中组合单一用途的工具类来应用样式，例如使用 flex、items-center、p-6、shadow-lg 等类组合出卡片布局。

移动优先响应式设计：无前缀工具类适用于所有屏幕尺寸，带前缀工具类在指定断点及以上生效。例如 <img class="w-16 md:w-32 lg:w-48" src="..." /> 表示移动端宽度 16、中等屏幕 32、大屏幕 48。

状态变体：为工具类添加状态前缀以有条件地应用样式，如 hover:、focus:、dark: 等。

安装方式

使用 Vite（推荐）：

1. 安装依赖：npm install tailwindcss @tailwindcss/vite
2. 在 vite.config.ts 中配置插件：

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

1. 在 CSS 文件中导入：@import "tailwindcss";
2. 启动开发：npm run dev

使用 PostCSS：

1. 安装依赖：npm install tailwindcss @tailwindcss/postcss
2. 在 postcss.config.js 中配置：

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

1. 在 CSS 文件中导入：@import "tailwindcss";

使用 Tailwind CLI：

1. 安装：npm install -D tailwindcss
2. 创建含导入语句的输入 CSS：@import "tailwindcss";
3. 构建 CSS：npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

主要能力

• 布局：Flexbox（flex items-center justify-between gap-4）、Grid（grid grid-cols-3 gap-6）、容器（mx-auto max-w-7xl px-4）
• 排版：标题（text-4xl font-bold text-gray-900）、段落（text-base text-gray-600 leading-relaxed）、截断（truncate）
• 间距：内边距（p-6、px-4 py-2）、外边距（m-4、mt-8 mb-4）
• 颜色：背景（bg-blue-500）、文本（text-red-600）、边框（border border-gray-300）
• 响应式断点：sm (40rem/640px)、md (48rem/768px)、lg (64rem/1024px)、xl (80rem/1280px)、2xl (96rem/1536px)
• 状态变体：hover、focus、active、disabled、dark、group-hover
• 任意值：方括号语法，如 bg-[#1da1f2]、top-[117px]、grid-cols-[200px_1fr_1fr]、h-[calc(100vh-4rem)]、bg-(--brand-color)

定制

主题变量：在 @theme 中使用 CSS 变量定制设计令牌，如 --color-brand: #ff6347;、--font-sans: 'Inter', system-ui, sans-serif;、--spacing-18: 4.5rem;、--breakpoint-3xl: 120rem;。

自定义工具类：在 @layer utilities 中定义，如 .text-balance { text-wrap: balance; }。

减少重复：可提取为可复用组件（如 React 组件），或在 @layer components 中创建可复用 CSS 类（如 .btn-primary）。

框架集成

支持 Next.js、Laravel、SvelteKit、Vue/Nuxt、Angular、React 等框架，详细说明参见 references/framework-setup.md。

最佳实践

推荐：使用工具类快速原型开发、采用移动优先响应式模式、利用状态变体、为重复模式创建组件、使用主题变量、使用任意值做一次性定制。

避免：过度使用自定义 CSS、用 sm: 前缀定位移动端、重复长类名列表、忽略暗色模式、混用大量传统 CSS、不必要地使用 !important 覆盖、创建深度嵌套的自定义组件样式。

常见模式

提供卡片组件、表单输入、导航栏等示例代码，参见原始资料中的完整 HTML 片段。

故障排查

• 样式未生效：检查 Tailwind 是否在 CSS 中导入、构建是否运行、类是否被检测到、是否有冲突 CSS 覆盖。
• 响应式变体失效：添加 viewport meta 标签、使用移动优先方式、检查断点前缀拼写。
• 暗色模式失效：检查 dark: 变体配置及系统/手动偏好设置。
• 构建输出过大：Tailwind 默认只包含使用的工具类，检查源文件检测和文件模式。

参考资源

• references/framework-setup.md：框架特定安装指南
• references/utility-reference.md：按类别组织的工具类参考
• references/customization-guide.md：主题定制、插件、扩展深入指南
• 官方文档：https://tailwindcss.com/docs
• 在线演练场：https://play.tailwindcss.com
• GitHub：https://github.com/tailwindlabs/tailwindcss

快速参考

安装：npm install tailwindcss @tailwindcss/vite

Vite 配置：

import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })

CSS 导入：@import "tailwindcss";

常用工具类：

• 布局：flex、grid、block、inline-block
• 间距：p-4、m-2、gap-4、space-x-2
• 尺寸：w-full、h-screen、max-w-lg
• 排版：text-lg、font-bold、leading-relaxed
• 颜色：bg-blue-500、text-white、border-gray-300
• 响应式：md:flex-row、lg:grid-cols-3
• 状态：hover:bg-blue-700、focus:ring-2、dark:bg-gray-800