tailwind-css

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS

Build modern, responsive web interfaces using utility-first CSS with Tailwind CSS.

使用实用优先的CSS框架Tailwind CSS构建现代、响应式的Web界面。

Overview

概述

Tailwind CSS is a utility-first CSS framework that generates CSS by scanning HTML files, JavaScript components, and templates for class names. It provides single-purpose utility classes that compose together directly in markup, enabling rapid UI development without writing custom CSS.

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

Core Principles

核心原则

Utility-First Styling

实用优先的样式设计

Apply styles by combining single-purpose utility classes directly in markup:

html

<div class="mx-auto flex max-w-sm items-center gap-x-4 rounded-xl bg-white p-6 shadow-lg">
  <img class="size-12 shrink-0" src="/logo.svg" alt="Logo" />
  <div>
    <div class="text-xl font-medium text-black">Title</div>
    <p class="text-gray-500">Description text</p>
  </div>
</div>

直接在标记中组合单一用途的工具类来应用样式：

html

<div class="mx-auto flex max-w-sm items-center gap-x-4 rounded-xl bg-white p-6 shadow-lg">
  <img class="size-12 shrink-0" src="/logo.svg" alt="Logo" />
  <div>
    <div class="text-xl font-medium text-black">Title</div>
    <p class="text-gray-500">Description text</p>
  </div>
</div>

Mobile-First Responsive Design

移动端优先的响应式设计

Unprefixed utilities apply to all screen sizes. Prefixed utilities apply at specified breakpoint and above:

html

<!-- Width 16 on mobile, 32 on medium screens, 48 on large screens -->
<img class="w-16 md:w-32 lg:w-48" src="..." />

无前缀的工具类适用于所有屏幕尺寸。带前缀的工具类适用于指定断点及更大屏幕：

html

<!-- 移动端宽度为16，中等屏幕为32，大屏幕为48 -->
<img class="w-16 md:w-32 lg:w-48" src="..." />

State Variants

状态变体

Prefix utilities with state variants to apply styles conditionally:

html

<!-- Hover, focus, and dark mode variants -->
<button class="bg-sky-500 hover:bg-sky-700 focus:ring-2 dark:bg-sky-900">
  Save
</button>

为工具类添加状态变体前缀，可根据条件应用样式：

html

<!-- 悬停、聚焦和暗黑模式变体 -->
<button class="bg-sky-500 hover:bg-sky-700 focus:ring-2 dark:bg-sky-900">
  Save
</button>

Installation

安装

Using Vite (Recommended)

使用Vite（推荐）

Install dependencies:

bash

npm install tailwindcss @tailwindcss/vite

Configure Vite plugin in

vite.config.ts

typescript

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

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

Import Tailwind in CSS file:
css
```
@import "tailwindcss";
```
Start development:
bash
```
npm run dev
```

安装依赖:

bash

npm install tailwindcss @tailwindcss/vite

在
vite.config.ts
中配置Vite插件:

typescript

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

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

在CSS文件中导入Tailwind:
css
```
@import "tailwindcss";
```
启动开发服务:
bash
```
npm run dev
```

Using PostCSS

使用PostCSS

Install dependencies:

bash

npm install tailwindcss @tailwindcss/postcss

Configure PostCSS in

postcss.config.js

javascript

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

Import Tailwind in CSS file:
css
```
@import "tailwindcss";
```

安装依赖:

bash

npm install tailwindcss @tailwindcss/postcss

在
postcss.config.js
中配置PostCSS:

javascript

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

在CSS文件中导入Tailwind:
css
```
@import "tailwindcss";
```

Using Tailwind CLI

使用Tailwind CLI

Install globally or as dev dependency:
bash
```
npm install -D tailwindcss
```
Create input CSS with Tailwind imports:
css
```
@import "tailwindcss";
```

Build CSS:

bash

npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

全局安装或作为开发依赖安装:
bash
```
npm install -D tailwindcss
```
创建包含Tailwind导入的输入CSS:
css
```
@import "tailwindcss";
```

构建CSS:

bash

npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

Common Utility Patterns

常见工具类模式

Layout

布局

html

<!-- Flexbox -->
<div class="flex items-center justify-between gap-4">

<!-- Grid -->
<div class="grid grid-cols-3 gap-6">

<!-- Container with max width -->
<div class="mx-auto max-w-7xl px-4">

html

<!-- Flexbox布局 -->
<div class="flex items-center justify-between gap-4">

<!-- Grid布局 -->
<div class="grid grid-cols-3 gap-6">

<!-- 带最大宽度的容器 -->
<div class="mx-auto max-w-7xl px-4">

Typography

排版

html

<!-- Heading -->
<h1 class="text-4xl font-bold text-gray-900">

<!-- Paragraph -->
<p class="text-base text-gray-600 leading-relaxed">

<!-- Truncate text -->
<p class="truncate">

html

<!-- 标题 -->
<h1 class="text-4xl font-bold text-gray-900">

<!-- 段落 -->
<p class="text-base text-gray-600 leading-relaxed">

<!-- 文本截断 -->
<p class="truncate">

Spacing

间距

html

<!-- Padding -->
<div class="p-6">           <!-- All sides -->
<div class="px-4 py-2">     <!-- Horizontal and vertical -->

<!-- Margin -->
<div class="m-4">           <!-- All sides -->
<div class="mt-8 mb-4">     <!-- Top and bottom -->

html

<!-- 内边距 -->
<div class="p-6">           <!-- 所有方向 -->
<div class="px-4 py-2">     <!-- 水平和垂直方向 -->

<!-- 外边距 -->
<div class="m-4">           <!-- 所有方向 -->
<div class="mt-8 mb-4">     <!-- 顶部和底部 -->

Colors

颜色

html

<!-- Background -->
<div class="bg-blue-500">

<!-- Text -->
<p class="text-red-600">

<!-- Border -->
<div class="border border-gray-300">

html

<!-- 背景色 -->
<div class="bg-blue-500">

<!-- 文本颜色 -->
<p class="text-red-600">

<!-- 边框颜色 -->
<div class="border border-gray-300">

Responsive Design

响应式设计

html

<!-- Stack on mobile, row on medium+ screens -->
<div class="flex flex-col md:flex-row">

<!-- Different padding at breakpoints -->
<div class="p-4 md:p-6 lg:p-8">

<!-- Hide on mobile, show on large screens -->
<div class="hidden lg:block">

html

<!-- 移动端垂直堆叠，中等及以上屏幕横向排列 -->
<div class="flex flex-col md:flex-row">

<!-- 不同断点下的内边距 -->
<div class="p-4 md:p-6 lg:p-8">

<!-- 移动端隐藏，大屏幕显示 -->
<div class="hidden lg:block">

Breakpoints Reference

断点参考

Prefix	Min Width	CSS
`sm`	40rem (640px)	`@media (width >= 40rem)`
`md`	48rem (768px)	`@media (width >= 48rem)`
`lg`	64rem (1024px)	`@media (width >= 64rem)`
`xl`	80rem (1280px)	`@media (width >= 80rem)`
`2xl`	96rem (1536px)	`@media (width >= 96rem)`

前缀	最小宽度	CSS
`sm`	40rem (640px)	`@media (width >= 40rem)`
`md`	48rem (768px)	`@media (width >= 48rem)`
`lg`	64rem (1024px)	`@media (width >= 64rem)`
`xl`	80rem (1280px)	`@media (width >= 80rem)`
`2xl`	96rem (1536px)	`@media (width >= 96rem)`

State Variants

状态变体

Apply utilities based on element state:

html

<!-- Hover -->
<button class="bg-blue-500 hover:bg-blue-700">

<!-- Focus -->
<input class="border-gray-300 focus:border-blue-500 focus:ring-2">

<!-- Active -->
<button class="active:bg-blue-800">

<!-- Disabled -->
<button class="disabled:opacity-50 disabled:cursor-not-allowed">

<!-- Dark mode -->
<div class="bg-white dark:bg-gray-800">

<!-- Group hover (parent-based) -->
<a class="group">
  <span class="group-hover:underline">Link</span>
</a>

根据元素状态应用工具类：

html

<!-- 悬停状态 -->
<button class="bg-blue-500 hover:bg-blue-700">

<!-- 聚焦状态 -->
<input class="border-gray-300 focus:border-blue-500 focus:ring-2">

<!-- 激活状态 -->
<button class="active:bg-blue-800">

<!-- 禁用状态 -->
<button class="disabled:opacity-50 disabled:cursor-not-allowed">

<!-- 暗黑模式 -->
<div class="bg-white dark:bg-gray-800">

<!-- 父元素悬停（基于父元素的状态） -->
<a class="group">
  <span class="group-hover:underline">Link</span>
</a>

Arbitrary Values

任意值

Use square bracket syntax for one-off values:

html

<!-- Custom color -->
<div class="bg-[#1da1f2]">

<!-- Custom spacing -->
<div class="top-[117px]">

<!-- Complex grid -->
<div class="grid-cols-[200px_1fr_1fr]">

<!-- Using calc -->
<div class="h-[calc(100vh-4rem)]">

<!-- CSS variables -->
<div class="bg-(--brand-color)">

使用方括号语法定义一次性值：

html

<!-- 自定义颜色 -->
<div class="bg-[#1da1f2]">

<!-- 自定义间距 -->
<div class="top-[117px]">

<!-- 复杂网格 -->
<div class="grid-cols-[200px_1fr_1fr]">

<!-- 使用calc计算 -->
<div class="h-[calc(100vh-4rem)]">

<!-- CSS变量 -->
<div class="bg-(--brand-color)">

Customization

自定义配置

Theme Variables

主题变量

Customize design tokens using CSS variables in

@theme

css

@import "tailwindcss";

@theme {
  --color-brand: #ff6347;
  --font-sans: 'Inter', system-ui, sans-serif;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 120rem;
}

在

@theme

中使用CSS变量自定义设计标记：

css

@import "tailwindcss";

@theme {
  --color-brand: #ff6347;
  --font-sans: 'Inter', system-ui, sans-serif;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 120rem;
}

Adding Custom Utilities

添加自定义工具类

Define custom utilities in

@layer utilities

css

@import "tailwindcss";

@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
  
  .scrollbar-hide {
    scrollbar-width: none;
    &::-webkit-scrollbar {
      display: none;
    }
  }
}

在

@layer utilities

中定义自定义工具类：

css

@import "tailwindcss";

@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
  
  .scrollbar-hide {
    scrollbar-width: none;
    &::-webkit-scrollbar {
      display: none;
    }
  }
}

Managing Duplication

重复代码管理

Extract Components

提取组件

For repeated patterns, create reusable components:

jsx

// React component
export function Button({ variant, children }) {
  const baseClasses = "px-4 py-2 rounded-lg font-medium";
  const variants = {
    primary: "bg-blue-500 text-white hover:bg-blue-700",
    secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300"
  };
  
  return (
    <button className={`${baseClasses} ${variants[variant]}`}>
      {children}
    </button>
  );
}

对于重复出现的模式，创建可复用组件：

jsx

// React组件
export function Button({ variant, children }) {
  const baseClasses = "px-4 py-2 rounded-lg font-medium";
  const variants = {
    primary: "bg-blue-500 text-white hover:bg-blue-700",
    secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300"
  };
  
  return (
    <button className={`${baseClasses} ${variants[variant]}`}>
      {children}
    </button>
  );
}

Custom CSS Classes

自定义CSS类

For template-based projects, create reusable CSS classes:

css

@layer components {
  .btn-primary {
    border-radius: calc(infinity * 1px);
    background-color: var(--color-blue-500);
    padding-inline: var(--spacing-4);
    padding-block: var(--spacing-2);
    font-weight: var(--font-weight-semibold);
    color: white;
    
    &:hover {
      @media (hover: hover) {
        background-color: var(--color-blue-700);
      }
    }
  }
}

对于基于模板的项目，创建可复用的CSS类：

css

@layer components {
  .btn-primary {
    border-radius: calc(infinity * 1px);
    background-color: var(--color-blue-500);
    padding-inline: var(--spacing-4);
    padding-block: var(--spacing-2);
    font-weight: var(--font-weight-semibold);
    color: white;
    
    &:hover {
      @media (hover: hover) {
        background-color: var(--color-blue-700);
      }
    }
  }
}

Framework Integration

框架集成

Tailwind integrates with popular frameworks:

Next.js - Add
```
@tailwindcss/vite
```
to Next.js config
Laravel - Use Vite with Laravel Mix
SvelteKit - Add to Vite config
Vue/Nuxt - Vite plugin integration
Angular - Configure with build system
React - Vite or Create React App setup

Consult references/framework-setup.md
for detailed framework-specific instructions.

Tailwind可与主流框架集成：

Next.js - 在Next.js配置中添加
```
@tailwindcss/vite
```
Laravel - 将Vite与Laravel Mix配合使用
SvelteKit - 添加到Vite配置中
Vue/Nuxt - Vite插件集成
Angular - 与构建系统配合配置
React - Vite或Create React App配置

请参考**

references/framework-setup.md

**获取详细的框架专属配置说明。

Best Practices

最佳实践

DO

建议

Use utility classes for rapid prototyping and development
Apply mobile-first responsive design patterns
Leverage state variants for interactive elements
Create components for repeated UI patterns
Use theme variables for consistent design tokens
Compose utilities to build complex designs
Use arbitrary values for one-off customizations

使用工具类进行快速原型开发和功能开发
采用移动端优先的响应式设计模式
利用状态变体实现交互元素
为重复出现的UI模式创建组件
使用主题变量确保设计标记的一致性
组合工具类构建复杂设计
使用任意值实现一次性自定义需求

DON'T

不建议

Fight the utility-first approach with excessive custom CSS
Use
```
sm:
```
prefix to target mobile (use unprefixed instead)
Duplicate long class lists (extract components)
Ignore dark mode styling (
```
dark:
```
variant)
Mix Tailwind with large amounts of traditional CSS
Override utilities with
```
!important
```
unnecessarily
Create deeply nested custom component styles

用大量自定义CSS违背实用优先的设计理念
使用
```
sm:
```
前缀适配移动端（应使用无前缀的工具类）
重复冗长的类列表（应提取为组件）
忽略暗黑模式样式（
```
dark:
```
变体）
将Tailwind与大量传统CSS混合使用
不必要地用
```
!important
```
覆盖工具类
创建深度嵌套的自定义组件样式

Common Patterns

常见模式

Card Component

卡片组件

html

<div class="overflow-hidden rounded-lg bg-white shadow-md">
  <img class="h-48 w-full object-cover" src="image.jpg" alt="" />
  <div class="p-6">
    <h3 class="text-xl font-semibold">Card Title</h3>
    <p class="mt-2 text-gray-600">Card description text.</p>
    <button class="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-700">
      Action
    </button>
  </div>
</div>

html

<div class="overflow-hidden rounded-lg bg-white shadow-md">
  <img class="h-48 w-full object-cover" src="image.jpg" alt="" />
  <div class="p-6">
    <h3 class="text-xl font-semibold">Card Title</h3>
    <p class="mt-2 text-gray-600">Card description text.</p>
    <button class="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-700">
      Action
    </button>
  </div>
</div>

Form Input

表单输入框

html

<div class="space-y-2">
  <label class="block text-sm font-medium text-gray-700" for="email">
    Email
  </label>
  <input
    id="email"
    type="email"
    class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500"
    placeholder="you@example.com"
  />
</div>

html

<div class="space-y-2">
  <label class="block text-sm font-medium text-gray-700" for="email">
    Email
  </label>
  <input
    id="email"
    type="email"
    class="w-full rounded-lg border border-gray-300 px-4 py-2 focus:border-blue-500 focus:outline-none focus:ring-2 focus:ring-blue-500"
    placeholder="you@example.com"
  />
</div>

Navigation Bar

导航栏

html

<nav class="border-b border-gray-200 bg-white">
  <div class="mx-auto flex max-w-7xl items-center justify-between px-4 py-4">
    <div class="text-xl font-bold">Brand</div>
    <div class="hidden space-x-6 md:flex">
      <a href="#" class="text-gray-700 hover:text-blue-500">Home</a>
      <a href="#" class="text-gray-700 hover:text-blue-500">About</a>
      <a href="#" class="text-gray-700 hover:text-blue-500">Contact</a>
    </div>
  </div>
</nav>

html

<nav class="border-b border-gray-200 bg-white">
  <div class="mx-auto flex max-w-7xl items-center justify-between px-4 py-4">
    <div class="text-xl font-bold">Brand</div>
    <div class="hidden space-x-6 md:flex">
      <a href="#" class="text-gray-700 hover:text-blue-500">Home</a>
      <a href="#" class="text-gray-700 hover:text-blue-500">About</a>
      <a href="#" class="text-gray-700 hover:text-blue-500">Contact</a>
    </div>
  </div>
</nav>

Troubleshooting

故障排除

Styles not applying:

Verify Tailwind is imported in CSS
Check build process is running
Ensure classes are detected in source files
Confirm no conflicting CSS overriding utilities

Responsive variants not working:

Add viewport meta tag to HTML
```
<head>
```
Use mobile-first approach (unprefixed for mobile)
Check breakpoint prefix spelling

Dark mode not working:

Verify
```
dark:
```
variant is configured
Check system/manual dark mode preference
Ensure parent has dark mode class if using class strategy

Build output too large:

Tailwind only includes used utilities by default
Verify source file detection is working
Check for overly broad file patterns

样式未生效:

确认已在CSS文件中导入Tailwind
检查构建进程是否在运行
确保源文件中的类名能被检测到
确认没有冲突的CSS覆盖工具类

响应式变体不生效:

在HTML的
```
<head>
```
中添加viewport元标签
采用移动端优先的设计方式（无前缀工具类适配移动端）
检查断点前缀的拼写

暗黑模式不生效:

确认已配置
```
dark:
```
变体
检查系统/手动设置的暗黑模式偏好
如果使用类策略，确保父元素带有暗黑模式类

构建输出文件过大:

Tailwind默认只包含已使用的工具类
确认源文件检测功能正常
检查是否存在过于宽泛的文件匹配规则

Additional Resources

额外资源

Reference Files

参考文件

For detailed information:

references/framework-setup.md
- Framework-specific installation guides for Next.js, Laravel, Vue, Angular, and more
references/utility-reference.md
- Comprehensive utility class reference organized by category
references/customization-guide.md
- Deep dive on theme customization, plugins, and extending Tailwind

如需详细信息：

references/framework-setup.md
- 针对Next.js、Laravel、Vue、Angular等框架的专属安装指南
references/utility-reference.md
- 按类别整理的完整工具类参考手册
references/customization-guide.md
- 深入讲解主题定制、插件和Tailwind扩展

Official Documentation

官方文档

Tailwind CSS Docs - https://tailwindcss.com/docs
Playground - https://play.tailwindcss.com
GitHub - https://github.com/tailwindlabs/tailwindcss

Tailwind CSS官方文档 - https://tailwindcss.com/docs
在线游乐场 - https://play.tailwindcss.com
GitHub仓库 - https://github.com/tailwindlabs/tailwindcss

Quick Reference

快速参考

Installation:

bash

npm install tailwindcss @tailwindcss/vite

Vite Config:

typescript

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

Import in CSS:

css

@import "tailwindcss";

Common Utilities:

Layout:
```
flex
```
,
```
grid
```
,
```
block
```
,
```
inline-block
```
Spacing:
```
p-4
```
,
```
m-2
```
,
```
gap-4
```
,
```
space-x-2
```
Sizing:
```
w-full
```
,
```
h-screen
```
,
```
max-w-lg
```
Typography:
```
text-lg
```
,
```
font-bold
```
,
```
leading-relaxed
```
Colors:
```
bg-blue-500
```
,
```
text-white
```
,
```
border-gray-300
```
Responsive:
```
md:flex-row
```
,
```
lg:grid-cols-3
```

State:

hover:bg-blue-700

focus:ring-2

dark:bg-gray-800

安装:

bash

npm install tailwindcss @tailwindcss/vite

Vite配置:

typescript

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

在CSS中导入:

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