Back to Details

tailwindcss

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tailwind CSS Skill

Tailwind CSS 全面使用指南

Tailwind CSS is a utility-first CSS framework that enables rapid UI development by providing pre-built utility classes. It generates optimized CSS at build-time by scanning your project files, resulting in zero runtime overhead and minimal production bundles.
Tailwind CSS 是一个实用优先的CSS框架，通过提供预构建的工具类实现快速UI开发。它会在构建时扫描你的项目文件，生成经过优化的CSS，最终实现零运行时开销和极小的生产环境打包体积。

When to Use This Skill

适用场景

Use this skill when:
  • Building responsive layouts with mobile-first design
  • Implementing dark mode and theme customization
  • Creating custom design systems with consistent spacing, colors, and typography
  • Styling React, Vue, Svelte, or any web framework components
  • Prototyping interfaces with rapid visual feedback
  • Building production applications with optimized CSS bundles
  • Working with state-based styling (hover, focus, disabled, etc.)
  • Creating complex layouts with Grid and Flexbox utilities
在以下场景中使用本指南：
  • 采用移动优先设计构建响应式布局
  • 实现深色模式和主题自定义
  • 创建具有一致间距、颜色和排版的自定义设计系统
  • 为React、Vue、Svelte或任何Web框架的组件添加样式
  • 通过快速视觉反馈制作界面原型
  • 构建具有优化CSS包的生产环境应用
  • 处理基于状态的样式（悬停、聚焦、禁用等）
  • 使用Grid和Flexbox工具类创建复杂布局

Core Concepts

核心概念

Utility-First Approach

实用优先的方法

Tailwind provides low-level utility classes that you apply directly to HTML elements instead of writing custom CSS:
html
<!-- Traditional CSS approach -->
<div class="card">
	<h2 class="card-title">Title</h2>
</div>

<!-- Tailwind utility-first approach -->
<div class="rounded-lg bg-white p-6 shadow-md">
	<h2 class="text-2xl font-bold text-gray-900">Title</h2>
</div>
Benefits:
  • No CSS file switching - styles live with markup
  • No naming conventions needed
  • Automatic dead code elimination
  • Consistent design tokens across team
  • Fast iteration without CSS bloat
Tailwind提供低级别的工具类，你可以直接将其应用于HTML元素，而无需编写自定义CSS：
html
<!-- 传统CSS方法 -->
<div class="card">
	<h2 class="card-title">Title</h2>
</div>

<!-- Tailwind实用优先方法 -->
<div class="rounded-lg bg-white p-6 shadow-md">
	<h2 class="text-2xl font-bold text-gray-900">Title</h2>
</div>
优势：
  • 无需在CSS文件间切换——样式与标记共存
  • 无需命名约定
  • 自动消除无用代码
  • 团队内保持一致的设计标记
  • 快速迭代，避免CSS冗余

Build-Time Processing

构建时处理

Tailwind scans your source files at build-time and generates only the CSS classes you actually use:
javascript
// Tailwind analyzes these files
content: [
	"./src/**/*.{js,jsx,ts,tsx}",
	"./app/**/*.{js,jsx,ts,tsx}",
	"./components/**/*.{js,jsx,ts,tsx}",
];
Result: Optimized production bundles with zero runtime overhead.
Tailwind会在构建时扫描你的源文件，仅生成你实际使用的CSS类：
javascript
// Tailwind分析这些文件
content: [
	"./src/**/*.{js,jsx,ts,tsx}",
	"./app/**/*.{js,jsx,ts,tsx}",
	"./components/**/*.{js,jsx,ts,tsx}",
];
结果：生成经过优化的生产环境包，零运行时开销。

Installation & Setup

安装与设置

Modern Setup with Vite

使用Vite的现代设置

Step 1: Install dependencies
bash
npm install -D tailwindcss @tailwindcss/vite
步骤1：安装依赖
bash
npm install -D tailwindcss @tailwindcss/vite

or

或

pnpm add -D tailwindcss @tailwindcss/vite
pnpm add -D tailwindcss @tailwindcss/vite

or

或

yarn add -D tailwindcss @tailwindcss/vite

**Step 2: Configure Vite**

```javascript
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
	plugins: [tailwindcss()],
});
Step 3: Import in CSS
css
/* src/index.css */
@import "tailwindcss";
Step 4: Reference stylesheet in HTML
html
<!DOCTYPE html>
<html>
	<head>
		<link rel="stylesheet" href="./src/index.css" />
	</head>
	<body>
		<div class="bg-blue-500 p-4 text-white">Hello Tailwind!</div>
	</body>
</html>
yarn add -D tailwindcss @tailwindcss/vite

**步骤2：配置Vite**

```javascript
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
	plugins: [tailwindcss()],
});
步骤3：在CSS中导入
css
/* src/index.css */
@import "tailwindcss";
步骤4：在HTML中引用样式表
html
<!DOCTYPE html>
<html>
	<head>
		<link rel="stylesheet" href="./src/index.css" />
	</head>
	<body>
		<div class="bg-blue-500 p-4 text-white">Hello Tailwind!</div>
	</body>
</html>

Framework-Specific Setup

针对特定框架的设置

Next.js (App Router):
bash
npx create-next-app@latest --tailwind
Next.js (Manual):
javascript
// tailwind.config.js
module.exports = {
	content: ["./app/**/*.{js,ts,jsx,tsx}", "./components/**/*.{js,ts,jsx,tsx}"],
};
React with Vite:
bash
npm create vite@latest my-app -- --template react
npm install -D tailwindcss @tailwindcss/vite
Vue:
bash
npm install -D tailwindcss @tailwindcss/vite
Svelte:
bash
npm install -D tailwindcss @tailwindcss/vite
Astro:
bash
npx astro add tailwind
Next.js（App Router）：
bash
npx create-next-app@latest --tailwind
Next.js（手动设置）：
javascript
// tailwind.config.js
module.exports = {
	content: ["./app/**/*.{js,ts,jsx,tsx}", "./components/**/*.{js,ts,jsx,tsx}"],
};
React + Vite：
bash
npm create vite@latest my-app -- --template react
npm install -D tailwindcss @tailwindcss/vite
Vue：
bash
npm install -D tailwindcss @tailwindcss/vite
Svelte：
bash
npm install -D tailwindcss @tailwindcss/vite
Astro：
bash
npx astro add tailwind

PostCSS Setup (Alternative)

PostCSS设置（替代方案）

bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
javascript
// postcss.config.js
export default {
	plugins: {
		tailwindcss: {},
		autoprefixer: {},
	},
};
bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
javascript
// postcss.config.js
export default {
	plugins: {
		tailwindcss: {},
		autoprefixer: {},
	},
};

Design System & Tokens

设计系统与标记

Default Design System

默认设计系统

Tailwind includes a comprehensive default design system:
  • Colors: 18 color palettes with 11 shades each (50-950)
  • Spacing: Consistent scale from 0.25rem to 96rem
  • Typography: Font sizes, weights, line heights
  • Breakpoints: Mobile-first responsive system
  • Shadows: Elevation system for depth
  • Border radius: Rounded corners at different scales
Tailwind包含一个全面的默认设计系统：
  • 颜色：18个调色板，每个包含11个色调（50-950）
  • 间距：从0.25rem到96rem的一致比例
  • 排版：字体大小、字重、行高
  • 断点：移动优先的响应式系统
  • 阴影：用于体现层级的阴影系统
  • 边框圆角：不同尺寸的圆角

Customizing Theme

自定义主题

Use the 
@theme
directive in CSS:
css
@import "tailwindcss";

@theme {
	/* Custom colors */
	--color-brand-50: oklch(0.97 0.02 264);
	--color-brand-500: oklch(0.55 0.22 264);
	--color-brand-900: oklch(0.25 0.15 264);

	/* Custom fonts */
	--font-display: "Satoshi", "Inter", sans-serif;
	--font-body: "Inter", system-ui, sans-serif;

	/* Custom spacing */
	--spacing-18: calc(var(--spacing) * 18);
	--spacing-navbar: 4.5rem;

	/* Custom breakpoints */
	--breakpoint-3xl: 120rem;
	--breakpoint-4xl: 160rem;

	/* Custom shadows */
	--shadow-glow: 0 0 20px rgba(139, 92, 246, 0.3);
}
Usage:
html
<div class="bg-brand-500 font-display shadow-glow">Custom themed element</div>
在CSS中使用
@theme
指令：
css
@import "tailwindcss";

@theme {
	/* 自定义颜色 */
	--color-brand-50: oklch(0.97 0.02 264);
	--color-brand-500: oklch(0.55 0.22 264);
	--color-brand-900: oklch(0.25 0.15 264);

	/* 自定义字体 */
	--font-display: "Satoshi", "Inter", sans-serif;
	--font-body: "Inter", system-ui, sans-serif;

	/* 自定义间距 */
	--spacing-18: calc(var(--spacing) * 18);
	--spacing-navbar: 4.5rem;

	/* 自定义断点 */
	--breakpoint-3xl: 120rem;
	--breakpoint-4xl: 160rem;

	/* 自定义阴影 */
	--shadow-glow: 0 0 20px rgba(139, 92, 246, 0.3);
}
使用方式：
html
<div class="bg-brand-500 font-display shadow-glow">自定义主题元素</div>

Color System

颜色系统

Using default colors:
html
<div class="bg-blue-500">Background</div>
<p class="text-red-600">Text</p>
<div class="border-green-400">Border</div>
Color scale:
  • 50: Lightest
  • 100-400: Light variations
  • 500: Base color
  • 600-800: Dark variations
  • 950: Darkest
Color opacity modifiers:
html
<div class="bg-black/75">75% opacity</div>
<div class="text-blue-500/30">30% opacity</div>
<div class="bg-purple-500/87">87% opacity</div>
使用默认颜色：
html
<div class="bg-blue-500">背景</div>
<p class="text-red-600">文本</p>
<div class="border-green-400">边框</div>
颜色层级：
  • 50：最浅
  • 100-400：浅色变体
  • 500：基础色
  • 600-800：深色变体
  • 950：最深
颜色透明度修饰符：
html
<div class="bg-black/75">75% 透明度</div>
<div class="text-blue-500/30">30% 透明度</div>
<div class="bg-purple-500/87">87% 透明度</div>

Utility Classes

工具类

Layout

布局

Display:
html
<div class="block">Block</div>
<div class="inline-block">Inline Block</div>
<div class="flex">Flex</div>
<div class="inline-flex">Inline Flex</div>
<div class="grid">Grid</div>
<div class="hidden">Hidden</div>
Flexbox:
html
<div class="flex items-center justify-between gap-4">
	<div>Item 1</div>
	<div>Item 2</div>
</div>

<div class="flex flex-col items-start">
	<div>Vertical stack</div>
</div>
Grid:
html
<div class="grid grid-cols-3 gap-4">
	<div>Column 1</div>
	<div>Column 2</div>
	<div>Column 3</div>
</div>

<div class="grid grid-cols-[1fr_500px_2fr] gap-6">
	<div>Flexible</div>
	<div>Fixed 500px</div>
	<div>More flexible</div>
</div>
Positioning:
html
<div class="relative">
	<div class="absolute top-0 right-0">Positioned</div>
</div>

<div class="fixed right-4 bottom-4">Fixed</div>
<div class="sticky top-0">Sticky header</div>
显示方式：
html
<div class="block">块级元素</div>
<div class="inline-block">行内块元素</div>
<div class="flex">Flex布局</div>
<div class="inline-flex">行内Flex布局</div>
<div class="grid">Grid布局</div>
<div class="hidden">隐藏元素</div>
Flexbox：
html
<div class="flex items-center justify-between gap-4">
	<div>项目1</div>
	<div>项目2</div>
</div>

<div class="flex flex-col items-start">
	<div>垂直堆叠</div>
</div>
Grid：
html
<div class="grid grid-cols-3 gap-4">
	<div>列1</div>
	<div>列2</div>
	<div>列3</div>
</div>

<div class="grid grid-cols-[1fr_500px_2fr] gap-6">
	<div>弹性宽度</div>
	<div>固定500px</div>
	<div>更宽的弹性宽度</div>
</div>
定位：
html
<div class="relative">
	<div class="absolute top-0 right-0">绝对定位元素</div>
</div>

<div class="fixed right-4 bottom-4">固定定位元素</div>
<div class="sticky top-0">粘性头部</div>

Spacing

间距

Padding & Margin:
html
<div class="p-4">Padding all sides</div>
<div class="px-6 py-3">Padding X and Y</div>
<div class="pt-8 pb-4">Padding top/bottom</div>
<div class="m-4">Margin all sides</div>
<div class="mx-auto">Center horizontally</div>
<div class="-mt-4">Negative margin</div>
Gap (Flexbox/Grid):
html
<div class="flex gap-4">Flex with gap</div>
<div class="grid grid-cols-3 gap-x-6 gap-y-4">Grid with X/Y gap</div>
内边距与外边距：
html
<div class="p-4">四边内边距</div>
<div class="px-6 py-3">水平/垂直内边距</div>
<div class="pt-8 pb-4">上下内边距</div>
<div class="m-4">四边外边距</div>
<div class="mx-auto">水平居中</div>
<div class="-mt-4">负外边距</div>
间距（Flexbox/Grid）：
html
<div class="flex gap-4">带间距的Flex布局</div>
<div class="grid grid-cols-3 gap-x-6 gap-y-4">带水平/垂直间距的Grid布局</div>

Typography

排版

Font Size:
html
<p class="text-xs">Extra small</p>
<p class="text-sm">Small</p>
<p class="text-base">Base (16px)</p>
<p class="text-lg">Large</p>
<p class="text-xl">Extra large</p>
<p class="text-2xl">2XL</p>
<h1 class="text-4xl font-bold">Heading</h1>
Font Weight:
html
<p class="font-light">Light (300)</p>
<p class="font-normal">Normal (400)</p>
<p class="font-medium">Medium (500)</p>
<p class="font-semibold">Semibold (600)</p>
<p class="font-bold">Bold (700)</p>
Text Alignment:
html
<p class="text-left">Left aligned</p>
<p class="text-center">Center aligned</p>
<p class="text-right">Right aligned</p>
<p class="text-justify">Justified</p>
Line Height:
html
<p class="leading-tight">Tight line height</p>
<p class="leading-normal">Normal line height</p>
<p class="leading-relaxed">Relaxed line height</p>
Combining font utilities:
html
<h1 class="text-4xl/tight font-bold">Font size 4xl with tight line-height</h1>
字体大小：
html
<p class="text-xs">特小字号</p>
<p class="text-sm">小字号</p>
<p class="text-base">基础字号（16px）</p>
<p class="text-lg">大字号</p>
<p class="text-xl">超大字号</p>
<p class="text-2xl">2XL字号</p>
<h1 class="text-4xl font-bold">标题</h1>
字重：
html
<p class="font-light">轻量（300）</p>
<p class="font-normal">常规（400）</p>
<p class="font-medium">中等（500）</p>
<p class="font-semibold">半粗体（600）</p>
<p class="font-bold">粗体（700）</p>
文本对齐：
html
<p class="text-left">左对齐</p>
<p class="text-center">居中对齐</p>
<p class="text-right">右对齐</p>
<p class="text-justify">两端对齐</p>
行高：
html
<p class="leading-tight">紧凑行高</p>
<p class="leading-normal">常规行高</p>
<p class="leading-relaxed">宽松行高</p>
组合字体工具类：
html
<h1 class="text-4xl/tight font-bold">字号4xl搭配紧凑行高</h1>

Colors & Backgrounds

颜色与背景

Background colors:
html
<div class="bg-white">White background</div>
<div class="bg-gray-100">Gray background</div>
<div class="bg-linear-to-r from-blue-500 to-purple-600">
	Gradient background
</div>
Text colors:
html
<p class="text-gray-900">Dark text</p>
<p class="text-blue-600">Blue text</p>
<a class="text-blue-500 hover:text-blue-700">Link</a>
背景色：
html
<div class="bg-white">白色背景</div>
<div class="bg-gray-100">灰色背景</div>
<div class="bg-linear-to-r from-blue-500 to-purple-600">
	渐变背景
</div>
文本颜色：
html
<p class="text-gray-900">深色文本</p>
<p class="text-blue-600">蓝色文本</p>
<a class="text-blue-500 hover:text-blue-700">链接</a>

Borders

边框

html
<div class="border">Default border</div>
<div class="border-2 border-gray-300">2px border</div>
<div class="border-t border-b-2">Top and bottom borders</div>
<div class="rounded-sm">Rounded corners</div>
<div class="rounded-lg">Large rounded</div>
<div class="rounded-full">Fully rounded</div>
<div class="rounded-md border border-red-500">Combined</div>
html
<div class="border">默认边框</div>
<div class="border-2 border-gray-300">2px灰色边框</div>
<div class="border-t border-b-2">上下边框</div>
<div class="rounded-sm">小圆角</div>
<div class="rounded-lg">大圆角</div>
<div class="rounded-full">全圆角</div>
<div class="rounded-md border border-red-500">组合样式</div>

Shadows

阴影

html
<div class="shadow-sm">Small shadow</div>
<div class="shadow-md">Medium shadow</div>
<div class="shadow-lg">Large shadow</div>
<div class="shadow-xl">Extra large shadow</div>
<div class="shadow-none">No shadow</div>
html
<div class="shadow-sm">小阴影</div>
<div class="shadow-md">中等阴影</div>
<div class="shadow-lg">大阴影</div>
<div class="shadow-xl">超大阴影</div>
<div class="shadow-none">无阴影</div>

Responsive Design

响应式设计

Mobile-First Breakpoints

移动优先断点

Tailwind uses a mobile-first approach. Base styles apply to all screen sizes, then use breakpoint prefixes to override at larger sizes:
Breakpoints:
  • sm:
    - 640px and up
  • md:
    - 768px and up
  • lg:
    - 1024px and up
  • xl:
    - 1280px and up
  • 2xl:
    - 1536px and up
Example:
html
<!-- Mobile: 1 column, Tablet: 2 columns, Desktop: 4 columns -->
<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
	<div>Item 1</div>
	<div>Item 2</div>
	<div>Item 3</div>
	<div>Item 4</div>
</div>

<!-- Hide on mobile, show on desktop -->
<div class="hidden lg:block">Desktop only content</div>

<!-- Show on mobile, hide on desktop -->
<div class="block lg:hidden">Mobile only content</div>

<!-- Responsive text sizes -->
<h1 class="text-2xl md:text-4xl lg:text-6xl">Responsive heading</h1>
Tailwind采用移动优先的方法。基础样式适用于所有屏幕尺寸，然后使用断点前缀在更大尺寸上覆盖样式：
断点：
  • sm:
    - 640px及以上
  • md:
    - 768px及以上
  • lg:
    - 1024px及以上
  • xl:
    - 1280px及以上
  • 2xl:
    - 1536px及以上
示例：
html
<!-- 移动端：1列，平板：2列，桌面端：4列 -->
<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
	<div>项目1</div>
	<div>项目2</div>
	<div>项目3</div>
	<div>项目4</div>
</div>

<!-- 移动端隐藏，桌面端显示 -->
<div class="hidden lg:block">仅桌面端可见内容</div>

<!-- 移动端显示，桌面端隐藏 -->
<div class="block lg:hidden">仅移动端可见内容</div>

<!-- 响应式字号 -->
<h1 class="text-2xl md:text-4xl lg:text-6xl">响应式标题</h1>

Custom Breakpoints

自定义断点

css
@theme {
	--breakpoint-3xl: 120rem;
	--breakpoint-tablet: 48rem;
}
html
<div class="tablet:grid-cols-2 3xl:grid-cols-6">Custom breakpoints</div>
css
@theme {
	--breakpoint-3xl: 120rem;
	--breakpoint-tablet: 48rem;
}
html
<div class="tablet:grid-cols-2 3xl:grid-cols-6">自定义断点</div>

Max-width Queries

最大宽度查询

html
<!-- Only apply styles below 768px -->
<div class="flex max-md:hidden">Hidden on mobile</div>

<!-- Between breakpoints -->
<div class="md:block lg:hidden">Only visible on tablets</div>
html
<!-- 仅在768px以下应用样式 -->
<div class="flex max-md:hidden">移动端隐藏</div>

<!-- 在断点之间显示 -->
<div class="md:block lg:hidden">仅平板可见</div>

Container Queries

容器查询

Style elements based on parent container width:
html
<div class="@container">
	<div class="@md:grid-cols-2 @lg:grid-cols-3">Responds to parent width</div>
</div>
根据父容器宽度设置元素样式：
html
<div class="@container">
	<div class="@md:grid-cols-2 @lg:grid-cols-3">根据父容器宽度响应</div>
</div>

Interactive States

交互状态

Hover States

悬停状态

html
<button class="bg-blue-500 text-white hover:bg-blue-700">Hover me</button>

<a class="text-blue-600 hover:underline"> Hover link </a>

<div class="scale-100 transition-transform hover:scale-105">Scale on hover</div>
html
<button class="bg-blue-500 text-white hover:bg-blue-700">悬停我</button>

<a class="text-blue-600 hover:underline"> 悬停链接 </a>

<div class="scale-100 transition-transform hover:scale-105">悬停时缩放</div>

Focus States

聚焦状态

html
<input class="border focus:border-blue-500 focus:ring-2 focus:ring-blue-200" />

<button
	class="bg-blue-500 focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
>
	Accessible button
</button>
html
<input class="border focus:border-blue-500 focus:ring-2 focus:ring-blue-200" />

<button
	class="bg-blue-500 focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
>
	无障碍按钮
</button>

Active States

激活状态

html
<button class="bg-blue-500 active:bg-blue-800">Click me</button>
html
<button class="bg-blue-500 active:bg-blue-800">点击我</button>

Disabled States

禁用状态

html
<button
	class="bg-blue-500 disabled:cursor-not-allowed disabled:opacity-50"
	disabled
>
	Disabled button
</button>

<input class="disabled:bg-gray-100" disabled />
html
<button
	class="bg-blue-500 disabled:cursor-not-allowed disabled:opacity-50"
	disabled
>
	禁用按钮
</button>

<input class="disabled:bg-gray-100" disabled />

Form States

表单状态

html
<input class="invalid:border-red-500 focus:invalid:ring-red-200" required />

<input
	class="placeholder:text-gray-400 placeholder:italic"
	placeholder="Search..."
/>

<input type="checkbox" class="checked:bg-blue-500" />
html
<input class="invalid:border-red-500 focus:invalid:ring-red-200" required />

<input
	class="placeholder:text-gray-400 placeholder:italic"
	placeholder="搜索..."
/>

<input type="checkbox" class="checked:bg-blue-500" />

Group Hover (Parent State)

组悬停（父元素状态）

html
<div class="group hover:bg-gray-100">
	<p class="group-hover:text-blue-600">Text changes when parent is hovered</p>
	<img class="group-hover:opacity-50" src="..." />
</div>
html
<div class="group hover:bg-gray-100">
	<p class="group-hover:text-blue-600">父元素悬停时文本变色</p>
	<img class="group-hover:opacity-50" src="..." />
</div>

Peer State (Sibling State)

同级状态（Peer State）

html
<input type="checkbox" class="peer" id="terms" />
<label for="terms" class="peer-checked:text-blue-600"> I accept terms </label>

<input type="email" class="peer" required />
<p class="hidden text-red-600 peer-invalid:block">Invalid email</p>
html
<input type="checkbox" class="peer" id="terms" />
<label for="terms" class="peer-checked:text-blue-600"> 我同意条款 </label>

<input type="email" class="peer" required />
<p class="hidden text-red-600 peer-invalid:block">无效邮箱</p>

Dark Mode

深色模式

Setup Dark Mode

设置深色模式

Media query approach (automatic):
html
<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
	Auto switches based on system preference
</div>
Class-based approach (manual toggle):
javascript
// Add .dark class to <html> element
document.documentElement.classList.toggle("dark");
媒体查询方式（自动切换）：
html
<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
	根据系统偏好自动切换
</div>
类名方式（手动切换）：
javascript
// 为<html>元素添加.dark类
document.documentElement.classList.toggle("dark");

Dark Mode Utilities

深色模式工具类

html
<!-- Colors -->
<div class="bg-white dark:bg-slate-900">Background</div>
<p class="text-gray-900 dark:text-gray-100">Text</p>

<!-- Borders -->
<div class="border-gray-200 dark:border-gray-700">Border</div>

<!-- Complete example -->
<div
	class="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900"
>
	<h2 class="text-2xl font-bold text-gray-900 dark:text-white">
		Dark mode card
	</h2>
	<p class="text-gray-600 dark:text-gray-300">Content adapts to theme</p>
</div>
html
<!-- 颜色 -->
<div class="bg-white dark:bg-slate-900">背景</div>
<p class="text-gray-900 dark:text-gray-100">文本</p>

<!-- 边框 -->
<div class="border-gray-200 dark:border-gray-700">边框</div>

<!-- 完整示例 -->
<div
	class="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900"
>
	<h2 class="text-2xl font-bold text-gray-900 dark:text-white">
		深色模式卡片
	</h2>
	<p class="text-gray-600 dark:text-gray-300">内容随主题适配</p>
</div>

Dark Mode Toggle Implementation

深色模式切换实现

javascript
// Store preference
function toggleDarkMode() {
	const isDark = document.documentElement.classList.toggle("dark");
	localStorage.setItem("theme", isDark ? "dark" : "light");
}

// Initialize on load
if (
	localStorage.theme === "dark" ||
	(!("theme" in localStorage) &&
		window.matchMedia("(prefers-color-scheme: dark)").matches)
) {
	document.documentElement.classList.add("dark");
}
javascript
// 存储偏好设置
function toggleDarkMode() {
	const isDark = document.documentElement.classList.toggle("dark");
	localStorage.setItem("theme", isDark ? "dark" : "light");
}

// 页面加载时初始化
if (
	localStorage.theme === "dark" ||
	(!("theme" in localStorage) &&
		window.matchMedia("(prefers-color-scheme: dark)").matches)
) {
	document.documentElement.classList.add("dark");
}

Arbitrary Values

任意值

Use square brackets for one-off custom values:
Pixel values:
html
<div class="top-[117px]">Custom position</div>
<p class="text-[22px]">Custom font size</p>
<div class="w-[500px]">Custom width</div>
Colors:
html
<div class="bg-[#bada55]">Custom hex color</div>
<div class="text-[rgb(123,45,67)]">RGB color</div>
<div class="bg-[oklch(0.55_0.22_264)]">OKLCH color</div>
CSS variables:
html
<div class="bg-(--my-brand-color)">CSS variable</div>
<div class="text-(length:--my-font-size)">Type hint</div>
Complex values:
html
<div class="grid-cols-[1fr_500px_2fr]">Custom grid</div>
<div class="content-['>']">Custom content</div>
<div class="mask-type-luminance">Custom property</div>
使用方括号定义一次性自定义值：
像素值：
html
<div class="top-[117px]">自定义定位</div>
<p class="text-[22px]">自定义字号</p>
<div class="w-[500px]">自定义宽度</div>
颜色：
html
<div class="bg-[#bada55]">自定义十六进制颜色</div>
<div class="text-[rgb(123,45,67)]">RGB颜色</div>
<div class="bg-[oklch(0.55_0.22_264)]">OKLCH颜色</div>
CSS变量：
html
<div class="bg-(--my-brand-color)">CSS变量</div>
<div class="text-(length:--my-font-size)">类型提示</div>
复杂值：
html
<div class="grid-cols-[1fr_500px_2fr]">自定义Grid布局</div>
<div class="content-['>']">自定义内容</div>
<div class="mask-type-luminance">自定义属性</div>

Transitions & Animations

过渡与动画

Transitions

过渡

html
<button class="bg-blue-500 transition-colors hover:bg-blue-700">
	Smooth color transition
</button>

<div class="transform transition-transform hover:scale-110">
	Scale with transition
</div>

<div class="transition-all duration-300 ease-in-out hover:shadow-lg">
	Multiple transitions
</div>

<!-- Duration options -->
<div class="transition duration-150">Fast</div>
<div class="transition duration-300">Normal</div>
<div class="transition duration-500">Slow</div>
html
<button class="bg-blue-500 transition-colors hover:bg-blue-700">
	平滑颜色过渡
</button>

<div class="transform transition-transform hover:scale-110">
	缩放过渡
</div>

<div class="transition-all duration-300 ease-in-out hover:shadow-lg">
	多属性过渡
</div>

<!-- 时长选项 -->
<div class="transition duration-150">快速</div>
<div class="transition duration-300">常规</div>
<div class="transition duration-500">慢速</div>

Transforms

变换

html
<!-- Scale -->
<div class="scale-95 hover:scale-100">Scale</div>

<!-- Rotate -->
<div class="rotate-45">Rotate 45deg</div>
<div class="hover:rotate-6">Slight rotation</div>

<!-- Translate -->
<div class="translate-x-4 translate-y-2">Move</div>

<!-- Skew -->
<div class="skew-x-12">Skew</div>

<!-- Combined -->
<div class="translate-x-2 scale-110 rotate-3 transform">
	Multiple transforms
</div>
html
<!-- 缩放 -->
<div class="scale-95 hover:scale-100">缩放</div>

<!-- 旋转 -->
<div class="rotate-45">旋转45度</div>
<div class="hover:rotate-6">轻微旋转</div>

<!-- 平移 -->
<div class="translate-x-4 translate-y-2">平移</div>

<!-- 倾斜 -->
<div class="skew-x-12">倾斜</div>

<!-- 组合变换 -->
<div class="translate-x-2 scale-110 rotate-3 transform">
	多变换组合
</div>

Animations

动画

html
<div class="animate-spin">Spinning</div>
<div class="animate-ping">Pinging</div>
<div class="animate-pulse">Pulsing</div>
<div class="animate-bounce">Bouncing</div>
html
<div class="animate-spin">旋转动画</div>
<div class="animate-ping">脉冲动画</div>
<div class="animate-pulse">心跳动画</div>
<div class="animate-bounce">弹跳动画</div>

Custom Animations

自定义动画

css
@theme {
	--animate-slide-in: slide-in 0.5s ease-out;
}

@keyframes slide-in {
	from {
		transform: translateX(-100%);
	}
	to {
		transform: translateX(0);
	}
}
html
<div class="animate-slide-in">Custom animation</div>
css
@theme {
	--animate-slide-in: slide-in 0.5s ease-out;
}

@keyframes slide-in {
	from {
		transform: translateX(-100%);
	}
	to {
		transform: translateX(0);
	}
}
html
<div class="animate-slide-in">自定义动画</div>

Advanced Patterns

高级模式

Custom Utilities

自定义工具类

Create reusable utility classes:
css
@utility content-auto {
	content-visibility: auto;
}

@utility tab-* {
	tab-size: var(--tab-size-*);
}
html
<div class="content-auto">Custom utility</div>
<pre class="tab-4">Custom tab size</pre>
创建可复用的工具类：
css
@utility content-auto {
	content-visibility: auto;
}

@utility tab-* {
	tab-size: var(--tab-size-*);
}
html
<div class="content-auto">自定义工具类</div>
<pre class="tab-4">自定义制表符大小</pre>

Custom Variants

自定义变体

css
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
@custom-variant aria-checked (&[aria-checked="true"]);
html
<div theme-midnight:bg-navy-900>Applies when data-theme="midnight"</div>
css
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
@custom-variant aria-checked (&[aria-checked="true"]);
html
<div theme-midnight:bg-navy-900>当data-theme="midnight"时应用样式</div>

Layer Organization

层级组织

css
@layer base {
	h1 {
		@apply text-4xl font-bold;
	}

	body {
		@apply bg-white text-gray-900;
	}
}

@layer components {
	.btn {
		@apply rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-700;
	}

	.card {
		@apply rounded-lg bg-white p-6 shadow-md;
	}
}
css
@layer base {
	h1 {
		@apply text-4xl font-bold;
	}

	body {
		@apply bg-white text-gray-900;
	}
}

@layer components {
	.btn {
		@apply rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-700;
	}

	.card {
		@apply rounded-lg bg-white p-6 shadow-md;
	}
}

Apply Directive

Apply指令

Extract repeated utilities into CSS classes:
css
.btn-primary {
	@apply rounded bg-blue-500 px-4 py-2 font-bold text-white hover:bg-blue-700;
}

.input-field {
	@apply rounded-md border border-gray-300 px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-hidden;
}
将重复的工具类提取到CSS类中：
css
.btn-primary {
	@apply rounded bg-blue-500 px-4 py-2 font-bold text-white hover:bg-blue-700;
}

.input-field {
	@apply rounded-md border border-gray-300 px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-hidden;
}

Component Examples

组件示例

Button Component

按钮组件

html
<!-- Primary button -->
<button
	class="transform rounded-lg bg-blue-600 px-6 py-3 font-semibold text-white shadow-md transition-all duration-200 hover:scale-105 hover:bg-blue-700 hover:shadow-lg focus:ring-4 focus:ring-blue-300 focus:outline-hidden active:bg-blue-800 disabled:cursor-not-allowed disabled:opacity-50"
>
	Click me
</button>

<!-- Secondary button -->
<button
	class="rounded-lg border-2 border-gray-300 bg-white px-6 py-3 font-semibold text-gray-700 hover:bg-gray-50"
>
	Secondary
</button>

<!-- Icon button -->
<button class="rounded-full p-2 transition-colors hover:bg-gray-100">
	<svg class="h-6 w-6">...</svg>
</button>
html
<!-- 主按钮 -->
<button
	class="transform rounded-lg bg-blue-600 px-6 py-3 font-semibold text-white shadow-md transition-all duration-200 hover:scale-105 hover:bg-blue-700 hover:shadow-lg focus:ring-4 focus:ring-blue-300 focus:outline-hidden active:bg-blue-800 disabled:cursor-not-allowed disabled:opacity-50"
>
	点击我
</button>

<!-- 次要按钮 -->
<button
	class="rounded-lg border-2 border-gray-300 bg-white px-6 py-3 font-semibold text-gray-700 hover:bg-gray-50"
>
	次要按钮
</button>

<!-- 图标按钮 -->
<button class="rounded-full p-2 transition-colors hover:bg-gray-100">
	<svg class="h-6 w-6">...</svg>
</button>

Card Component

卡片组件

html
<div
	class="overflow-hidden rounded-xl bg-white shadow-lg transition-shadow hover:shadow-xl dark:bg-gray-800"
>
	<img class="h-48 w-full object-cover" src="..." alt="Card image" />
	<div class="p-6">
		<h3 class="mb-2 text-2xl font-bold text-gray-900 dark:text-white">
			Card Title
		</h3>
		<p class="mb-4 text-gray-600 dark:text-gray-300">
			Card description text goes here
		</p>
		<button
			class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700"
		>
			Learn More
		</button>
	</div>
</div>
html
<div
	class="overflow-hidden rounded-xl bg-white shadow-lg transition-shadow hover:shadow-xl dark:bg-gray-800"
>
	<img class="h-48 w-full object-cover" src="..." alt="卡片图片" />
	<div class="p-6">
		<h3 class="mb-2 text-2xl font-bold text-gray-900 dark:text-white">
			卡片标题
		</h3>
		<p class="mb-4 text-gray-600 dark:text-gray-300">
			卡片描述文本
		</p>
		<button
			class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700"
		>
			了解更多
		</button>
	</div>
</div>

Form Component

表单组件

html
<form
	class="mx-auto max-w-md rounded-lg bg-white p-8 shadow-md dark:bg-gray-800"
>
	<div class="mb-6">
		<label
			class="mb-2 block font-semibold text-gray-700 dark:text-gray-300"
			for="email"
		>
			Email
		</label>
		<input
			type="email"
			id="email"
			class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 focus:outline-hidden dark:border-gray-600 dark:bg-gray-700 dark:text-white"
			placeholder="you@example.com"
		/>
	</div>

	<div class="mb-6">
		<label
			class="mb-2 block font-semibold text-gray-700 dark:text-gray-300"
			for="password"
		>
			Password
		</label>
		<input
			type="password"
			id="password"
			class="w-full rounded-lg border border-gray-300 px-4 py-2 invalid:border-red-500 focus:ring-2 focus:ring-blue-500 focus:outline-hidden dark:border-gray-600 dark:bg-gray-700 dark:text-white"
		/>
	</div>

	<button
		type="submit"
		class="w-full rounded-lg bg-blue-600 py-3 font-bold text-white transition-colors hover:bg-blue-700"
	>
		Sign In
	</button>
</form>
html
<form
	class="mx-auto max-w-md rounded-lg bg-white p-8 shadow-md dark:bg-gray-800"
>
	<div class="mb-6">
		<label
			class="mb-2 block font-semibold text-gray-700 dark:text-gray-300"
			for="email"
		>
			邮箱
		</label>
		<input
			type="email"
			id="email"
			class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 focus:outline-hidden dark:border-gray-600 dark:bg-gray-700 dark:text-white"
			placeholder="you@example.com"
		/>
	</div>

	<div class="mb-6">
		<label
			class="mb-2 block font-semibold text-gray-700 dark:text-gray-300"
			for="password"
		>
			密码
		</label>
		<input
			type="password"
			id="password"
			class="w-full rounded-lg border border-gray-300 px-4 py-2 invalid:border-red-500 focus:ring-2 focus:ring-blue-500 focus:outline-hidden dark:border-gray-600 dark:bg-gray-700 dark:text-white"
		/>
	</div>

	<button
		type="submit"
		class="w-full rounded-lg bg-blue-600 py-3 font-bold text-white transition-colors hover:bg-blue-700"
	>
		登录
	</button>
</form>

Navigation Component

导航组件

html
<nav class="sticky top-0 z-50 bg-white shadow-md dark:bg-gray-900">
	<div class="container mx-auto px-4">
		<div class="flex h-16 items-center justify-between">
			<div class="flex items-center gap-8">
				<a href="/" class="text-2xl font-bold text-blue-600">Logo</a>
				<div class="hidden gap-6 md:flex">
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>Home</a
					>
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>About</a
					>
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>Services</a
					>
				</div>
			</div>
			<button
				class="rounded-sm p-2 hover:bg-gray-100 md:hidden dark:hover:bg-gray-800"
			>
				<svg class="h-6 w-6">...</svg>
			</button>
		</div>
	</div>
</nav>
html
<nav class="sticky top-0 z-50 bg-white shadow-md dark:bg-gray-900">
	<div class="container mx-auto px-4">
		<div class="flex h-16 items-center justify-between">
			<div class="flex items-center gap-8">
				<a href="/" class="text-2xl font-bold text-blue-600">Logo</a>
				<div class="hidden gap-6 md:flex">
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>首页</a
					>
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>关于我们</a
					>
					<a
						href="#"
						class="text-gray-700 transition-colors hover:text-blue-600 dark:text-gray-300"
						>服务</a
					>
				</div>
			</div>
			<button
				class="rounded-sm p-2 hover:bg-gray-100 md:hidden dark:hover:bg-gray-800"
			>
				<svg class="h-6 w-6">...</svg>
			</button>
		</div>
	</div>
</nav>

Grid Layout

Grid布局

html
<div class="container mx-auto px-4 py-8">
	<div
		class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
	>
		<div class="rounded-lg bg-white p-6 shadow-md">Item 1</div>
		<div class="rounded-lg bg-white p-6 shadow-md">Item 2</div>
		<div class="rounded-lg bg-white p-6 shadow-md">Item 3</div>
		<div class="rounded-lg bg-white p-6 shadow-md">Item 4</div>
	</div>
</div>
html
<div class="container mx-auto px-4 py-8">
	<div
		class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
	>
		<div class="rounded-lg bg-white p-6 shadow-md">项目1</div>
		<div class="rounded-lg bg-white p-6 shadow-md">项目2</div>
		<div class="rounded-lg bg-white p-6 shadow-md">项目3</div>
		<div class="rounded-lg bg-white p-6 shadow-md">项目4</div>
	</div>
</div>

Best Practices

最佳实践

1. Use Consistent Spacing Scale

1. 使用一致的间距比例

html
<!-- Good: Use spacing scale -->
<div class="mb-6 p-4">
	<!-- Avoid: Arbitrary values unless necessary -->
	<div class="mb-[23px] p-[17px]"></div>
</div>
html
<!-- 推荐：使用内置间距比例 -->
<div class="mb-6 p-4">
	<!-- 避免：除非必要，否则不要使用任意值 -->
	<div class="mb-[23px] p-[17px]"></div>
</div>

2. Leverage Design Tokens

2. 利用设计标记

html
<!-- Good: Use semantic color names -->
<button class="bg-blue-600 hover:bg-blue-700">
	<!-- Avoid: One-off colors -->
	<button class="bg-[#3B82F6] hover:bg-[#2563EB]"></button>
</button>
html
<!-- 推荐：使用语义化颜色名称 -->
<button class="bg-blue-600 hover:bg-blue-700">
	<!-- 避免：一次性颜色值 -->
	<button class="bg-[#3B82F6] hover:bg-[#2563EB]"></button>
</button>

3. Mobile-First Responsive Design

3. 移动优先的响应式设计

html
<!-- Good: Mobile first, then scale up -->
<div class="text-base md:text-lg lg:text-xl">
	<!-- Avoid: Desktop first -->
	<div class="text-xl lg:text-base"></div>
</div>
html
<!-- 推荐：移动优先，然后向上适配 -->
<div class="text-base md:text-lg lg:text-xl">
	<!-- 避免：桌面优先 -->
	<div class="text-xl lg:text-base"></div>
</div>

4. Component Extraction

4. 组件提取

javascript
// React component with Tailwind
function Button({ children, variant = "primary" }) {
	const baseClasses = "font-semibold px-6 py-3 rounded-lg transition-colors";
	const variants = {
		primary: "bg-blue-600 hover:bg-blue-700 text-white",
		secondary: "bg-gray-200 hover:bg-gray-300 text-gray-900",
	};

	return (
		<button className={`${baseClasses} ${variants[variant]}`}>
			{children}
		</button>
	);
}
javascript
// 使用Tailwind的React组件
function Button({ children, variant = "primary" }) {
	const baseClasses = "font-semibold px-6 py-3 rounded-lg transition-colors";
	const variants = {
		primary: "bg-blue-600 hover:bg-blue-700 text-white",
		secondary: "bg-gray-200 hover:bg-gray-300 text-gray-900",
	};

	return (
		<button className={`${baseClasses} ${variants[variant]}`}>
			{children}
		</button>
	);
}

5. Use @apply for Repeated Patterns

5. 使用@apply处理重复模式

css
/* Only use @apply for truly repeated patterns */
@layer components {
	.card {
		@apply rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg;
	}
}
css
/* 仅对真正重复的模式使用@apply */
@layer components {
	.card {
		@apply rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg;
	}
}

6. Accessibility First

6. 优先考虑无障碍性

html
<button class="focus:ring-4 focus:ring-blue-300 focus:outline-hidden">
	Accessible button
</button>

<a class="text-blue-600 hover:underline focus:outline-2 focus:outline-offset-2">
	Accessible link
</a>
html
<button class="focus:ring-4 focus:ring-blue-300 focus:outline-hidden">
	无障碍按钮
</button>

<a class="text-blue-600 hover:underline focus:outline-2 focus:outline-offset-2">
	无障碍链接
</a>

7. Performance Optimization

7. 性能优化

  • Use PurgeCSS in production (automatic with modern setup)
  • Avoid dynamic class names: 
    class={
    text-${color}-500
    }
    won't work
  • Use safelist for dynamic classes if needed
  • 在生产环境中使用PurgeCSS（现代设置会自动处理）
  • 避免动态类名：
    class={
    text-${color}-500
    }
    无法生效
  • 如有需要，为动态类名添加安全列表

8. Dark Mode Consistency

8. 深色模式一致性

html
<!-- Ensure all elements have dark mode variants -->
<div
	class="border border-gray-200 bg-white text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-white"
>
	Complete dark mode support
</div>
html
<!-- 确保所有元素都有深色模式变体 -->
<div
	class="border border-gray-200 bg-white text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-white"
>
	完整的深色模式支持
</div>

Common Patterns

常见模式

Centering Content

内容居中

html
<!-- Horizontal center -->
<div class="flex justify-center">Content</div>
<div class="mx-auto w-fit">Content</div>

<!-- Vertical center -->
<div class="flex h-screen items-center">Content</div>

<!-- Center both axes -->
<div class="flex h-screen items-center justify-center">Centered content</div>
html
<!-- 水平居中 -->
<div class="flex justify-center">内容</div>
<div class="mx-auto w-fit">内容</div>

<!-- 垂直居中 -->
<div class="flex h-screen items-center">内容</div>

<!-- 水平垂直居中 -->
<div class="flex h-screen items-center justify-center">居中内容</div>

Full-Width Container with Max Width

全宽容器带最大宽度

html
<div class="container mx-auto max-w-7xl px-4">
	Content with consistent max width
</div>
html
<div class="container mx-auto max-w-7xl px-4">
	具有一致最大宽度的内容
</div>

Aspect Ratio Boxes

宽高比盒子

html
<div class="aspect-square">Square</div>
<div class="aspect-video">16:9 video</div>
<div class="aspect-4/3">4:3 ratio</div>
html
<div class="aspect-square">正方形</div>
<div class="aspect-video">16:9视频比例</div>
<div class="aspect-4/3">4:3比例</div>

Truncate Text

文本截断

html
<p class="truncate">Long text that will be truncated with ellipsis...</p>

<p class="line-clamp-3">
	Long text that will be truncated after 3 lines with ellipsis...
</p>
html
<p class="truncate">过长文本将被截断并显示省略号...</p>

<p class="line-clamp-3">
	过长文本将在3行后截断并显示省略号...
</p>

Smooth Scrolling

平滑滚动

html
<html class="scroll-smooth">
	<a href="#section">Smooth scroll to section</a>
</html>
html
<html class="scroll-smooth">
	<a href="#section">平滑滚动到指定区域</a>
</html>

Troubleshooting

故障排除

Classes Not Working

类不生效

  1. Check content configuration:
javascript
// tailwind.config.js
content: [
	"./src/**/*.{js,jsx,ts,tsx}",
	// Add all file paths where you use Tailwind
];
  1. Dynamic classes won't work:
javascript
// ❌ Won't work
const color = 'blue'
<div className={`text-${color}-500`} />

// ✅ Works
<div className={color === 'blue' ? 'text-blue-500' : 'text-red-500'} />
  1. Specificity issues:
css
/* Use !important sparingly */
<div class="text-red-500!">Overrides other styles</div>
  1. 检查内容配置：
javascript
// tailwind.config.js
content: [
	"./src/**/*.{js,jsx,ts,tsx}",
	// 添加所有使用Tailwind的文件路径
];
  1. 动态类名无法生效：
javascript
// ❌ 无法生效
const color = 'blue'
<div className={`text-${color}-500`} />

// ✅ 可以生效
<div className={color === 'blue' ? 'text-blue-500' : 'text-red-500'} />
  1. 优先级问题：
css
// 谨慎使用!important
<div class="text-red-500!">覆盖其他样式</div>

Build Issues

构建问题

bash
undefined
bash
// 清除缓存并重新构建
rm -rf .next node_modules/.cache
npm run dev

Clear cache and rebuild

智能提示不生效

rm -rf .next node_modules/.cache npm run dev
undefined
安装官方扩展：
  • VS Code："Tailwind CSS IntelliSense"
  • 在
    .vscode/settings.json
    中配置：
json
{
	"tailwindCSS.experimental.classRegex": [
		["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
	]
}

IntelliSense Not Working

资源

Install official extension:
  • VS Code: "Tailwind CSS IntelliSense"
  • Configure in 
    .vscode/settings.json
    :
json
{
	"tailwindCSS.experimental.classRegex": [
		["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
	]
}

Resources

框架集成示例

—

React

jsx
export function Card({ title, description }) {
	return (
		<div className="rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg">
			<h3 className="mb-2 text-2xl font-bold">{title}</h3>
			<p className="text-gray-600">{description}</p>
		</div>
	);
}

Framework Integration Examples

Vue

React

—
jsx
export function Card({ title, description }) {
	return (
		<div className="rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg">
			<h3 className="mb-2 text-2xl font-bold">{title}</h3>
			<p className="text-gray-600">{description}</p>
		</div>
	);
}
vue
<template>
	<div
		class="rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg"
	>
		<h3 class="mb-2 text-2xl font-bold">{{ title }}</h3>
		<p class="text-gray-600">{{ description }}</p>
	</div>
</template>

<script setup>
defineProps(["title", "description"]);
</script>

Vue

Svelte

vue
<template>
	<div
		class="rounded-lg bg-white p-6 shadow-md transition-shadow hover:shadow-lg"
	>
		<h3 class="mb-2 text-2xl font-bold">{{ title }}</h3>
		<p class="text-gray-600">{{ description }}</p>
	</div>
</template>

<script setup>
defineProps(["title", "description"]);
</script>
svelte
<script>
  export let title
  export let description
</script>

<div class="bg-white rounded-lg shadow-md p-6 hover:shadow-lg transition-shadow">
  <h3 class="text-2xl font-bold mb-2">{title}</h3>
  <p class="text-gray-600">{description}</p>
</div>

Svelte

实施检查清单

svelte
<script>
  export let title
  export let description
</script>

<div class="bg-white rounded-lg shadow-md p-6 hover:shadow-lg transition-shadow">
  <h3 class="text-2xl font-bold mb-2">{title}</h3>
  <p class="text-gray-600">{description}</p>
</div>
实施Tailwind CSS时：
  • 安装
    tailwindcss
    和对应框架的插件
  • 配置构建工具（Vite/PostCSS/CLI）
  • 在配置中设置内容路径
  • 在CSS文件中导入Tailwind
  • 配置自定义主题标记（如有需要）
  • 设置深色模式策略
  • 安装VS Code智能提示扩展
  • 创建可复用的组件模式
  • 实现响应式断点
  • 添加无障碍聚焦状态
  • 在所有组件中测试深色模式
  • 优化生产环境构建
  • 文档化自定义工具类和组件

Implementation Checklist

—
When implementing Tailwind CSS:
  • Install 
    tailwindcss
    and framework-specific plugin
  • Configure build tool (Vite/PostCSS/CLI)
  • Set up content paths in configuration
  • Import Tailwind in CSS file
  • Configure custom theme tokens (if needed)
  • Set up dark mode strategy
  • Install VS Code IntelliSense extension
  • Create reusable component patterns
  • Implement responsive breakpoints
  • Add accessibility focus states
  • Test dark mode across all components
  • Optimize for production build
  • Document custom utilities and components
—