tailwindcss

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS v4 Development Guidelines

Tailwind CSS v4 开发指南

Best practices for using Tailwind CSS v4 utility classes effectively.

Note: Tailwind CSS v4 (released January 2025) uses a CSS-first configuration approach. If you need v3 compatibility, tailwind.config.js is still supported.

有效使用Tailwind CSS v4工具类的最佳实践。

注意：Tailwind CSS v4（2025年1月发布）采用CSS优先的配置方式。如果需要兼容v3版本，tailwind.config.js仍然被支持。

Core Principles

核心原则

Utility-First: Use utility classes instead of custom CSS
Mobile-First: Design for mobile, then scale up with responsive modifiers
Component Extraction: Extract repeated patterns into components
Consistent Spacing: Use Tailwind's spacing scale
Custom Configuration: Extend the default theme for brand consistency

工具类优先：使用工具类而非自定义CSS
移动优先：先为移动端设计，再通过响应式修饰符适配大屏
组件提取：将重复的样式模式提取为组件
间距一致性：使用Tailwind的间距刻度
自定义配置：扩展默认主题以保持品牌一致性

Basic Utilities

基础工具类

Layout

布局

tsx

// Flexbox
<div className="flex items-center justify-between gap-4">
  <div className="flex-1">Content</div>
  <div className="flex-shrink-0">Sidebar</div>
</div>

// Grid
<div className="grid grid-cols-3 gap-4">
  <div>1</div>
  <div>2</div>
  <div>3</div>
</div>

// Positioning
<div className="relative">
  <div className="absolute top-0 right-0">Badge</div>
</div>

tsx

// Flexbox
<div className="flex items-center justify-between gap-4">
  <div className="flex-1">Content</div>
  <div className="flex-shrink-0">Sidebar</div>
</div>

// Grid
<div className="grid grid-cols-3 gap-4">
  <div>1</div>
  <div>2</div>
  <div>3</div>
</div>

// Positioning
<div className="relative">
  <div className="absolute top-0 right-0">Badge</div>
</div>

Spacing

间距

tsx

// Padding and Margin
<div className="p-4 m-2">           {/* padding: 1rem, margin: 0.5rem */}
<div className="px-6 py-4">        {/* padding-x: 1.5rem, padding-y: 1rem */}
<div className="mt-8 mb-4">        {/* margin-top: 2rem, margin-bottom: 1rem */}

// Space between children
<div className="space-y-4">        {/* margin-bottom on all but last child */}
  <div>Item 1</div>
  <div>Item 2</div>
</div>

tsx

// Padding and Margin
<div className="p-4 m-2">           {/* padding: 1rem, margin: 0.5rem */}
<div className="px-6 py-4">        {/* padding-x: 1.5rem, padding-y: 1rem */}
<div className="mt-8 mb-4">        {/* margin-top: 2rem, margin-bottom: 1rem */}

// Space between children
<div className="space-y-4">        {/* margin-bottom on all but last child */}
  <div>Item 1</div>
  <div>Item 2</div>
</div>

Typography

排版

tsx

<h1 className="text-4xl font-bold text-gray-900">Heading</h1>
<p className="text-base font-normal text-gray-600 leading-relaxed">
  Paragraph text with comfortable line height.
</p>
<span className="text-sm font-medium text-blue-600">Label</span>

tsx

<h1 className="text-4xl font-bold text-gray-900">Heading</h1>
<p className="text-base font-normal text-gray-600 leading-relaxed">
  Paragraph text with comfortable line height.
</p>
<span className="text-sm font-medium text-blue-600">Label</span>

Colors

颜色

tsx

// Text colors
<p className="text-gray-900 dark:text-gray-100">Text</p>

// Background colors
<div className="bg-blue-500 hover:bg-blue-600">Button</div>

// Border colors
<div className="border border-gray-300">Box</div>

tsx

// Text colors
<p className="text-gray-900 dark:text-gray-100">Text</p>

// Background colors
<div className="bg-blue-500 hover:bg-blue-600">Button</div>

// Border colors
<div className="border border-gray-300">Box</div>

Responsive Design

响应式设计

Breakpoints

断点

tsx

// Mobile-first responsive classes
<div className="w-full md:w-1/2 lg:w-1/3">
  {/* Full width on mobile, half on medium screens, third on large */}
</div>

<h1 className="text-2xl md:text-4xl lg:text-6xl">
  {/* Responsive text sizes */}
</h1>

<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
  {/* Responsive grid */}
</div>

tsx

// Mobile-first responsive classes
<div className="w-full md:w-1/2 lg:w-1/3">
  {/* Full width on mobile, half on medium screens, third on large */}
</div>

<h1 className="text-2xl md:text-4xl lg:text-6xl">
  {/* Responsive text sizes */}
</h1>

<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
  {/* Responsive grid */}
</div>

Container

容器

tsx

<div className="container mx-auto px-4">
  {/* Centered container with horizontal padding */}
</div>

<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
  {/* Responsive container padding */}
</div>

tsx

<div className="container mx-auto px-4">
  {/* Centered container with horizontal padding */}
</div>

<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
  {/* Responsive container padding */}
</div>

Component Patterns

组件模式

Button

按钮

tsx

<button className="px-4 py-2 bg-blue-600 text-white font-medium rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
  Click me
</button>

// Variants
<button className="px-4 py-2 border border-gray-300 rounded-md hover:bg-gray-50">
  Secondary
</button>

tsx

<button className="px-4 py-2 bg-blue-600 text-white font-medium rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
  Click me
</button>

// Variants
<button className="px-4 py-2 border border-gray-300 rounded-md hover:bg-gray-50">
  Secondary
</button>

Card

卡片

tsx

<div className="bg-white rounded-lg shadow-md overflow-hidden">
  <img src="/image.jpg" alt="" className="w-full h-48 object-cover" />
  <div className="p-6">
    <h2 className="text-xl font-semibold mb-2">Card Title</h2>
    <p className="text-gray-600">Card content goes here.</p>
  </div>
</div>

tsx

<div className="bg-white rounded-lg shadow-md overflow-hidden">
  <img src="/image.jpg" alt="" className="w-full h-48 object-cover" />
  <div className="p-6">
    <h2 className="text-xl font-semibold mb-2">Card Title</h2>
    <p className="text-gray-600">Card content goes here.</p>
  </div>
</div>

Form Input

表单输入框

tsx

<div className="space-y-2">
  <label htmlFor="email" className="block text-sm font-medium text-gray-700">
    Email
  </label>
  <input
    type="email"
    id="email"
    className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
    placeholder="you@example.com"
  />
  <p className="text-sm text-gray-500">We'll never share your email.</p>
</div>

tsx

<div className="space-y-2">
  <label htmlFor="email" className="block text-sm font-medium text-gray-700">
    Email
  </label>
  <input
    type="email"
    id="email"
    className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
    placeholder="you@example.com"
  />
  <p className="text-sm text-gray-500">We'll never share your email.</p>
</div>

State Variants

状态变体

Hover, Focus, Active

悬停、聚焦、激活

tsx

<button className="bg-blue-500 hover:bg-blue-600 active:bg-blue-700 focus:ring-2 focus:ring-blue-500">
  Interactive Button
</button>

<a href="#" className="text-blue-600 hover:text-blue-800 hover:underline">
  Link
</a>

tsx

<button className="bg-blue-500 hover:bg-blue-600 active:bg-blue-700 focus:ring-2 focus:ring-blue-500">
  Interactive Button
</button>

<a href="#" className="text-blue-600 hover:text-blue-800 hover:underline">
  Link
</a>

Group Hover

组悬停

tsx

<div className="group">
  <img src="/image.jpg" className="group-hover:opacity-75 transition-opacity" />
  <p className="group-hover:text-blue-600">Hover the container</p>
</div>

tsx

<div className="group">
  <img src="/image.jpg" className="group-hover:opacity-75 transition-opacity" />
  <p className="group-hover:text-blue-600">Hover the container</p>
</div>

Disabled

禁用状态

tsx

<button className="disabled:opacity-50 disabled:cursor-not-allowed" disabled>
  Disabled Button
</button>

tsx

<button className="disabled:opacity-50 disabled:cursor-not-allowed" disabled>
  Disabled Button
</button>

Dark Mode

深色模式

css

/* Tailwind v4: Configure in app/globals.css */
@import "tailwindcss";

@media (prefers-color-scheme: dark) {
  /* Or use class-based: .dark */
}

tsx

// Usage (same as v3)
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  <h1 className="text-gray-900 dark:text-white">Title</h1>
  <p className="text-gray-600 dark:text-gray-400">Description</p>
</div>

css

/* Tailwind v4: Configure in app/globals.css */
@import "tailwindcss";

@media (prefers-color-scheme: dark) {
  /* Or use class-based: .dark */
}

tsx

// Usage (same as v3)
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  <h1 className="text-gray-900 dark:text-white">Title</h1>
  <p className="text-gray-600 dark:text-gray-400">Description</p>
</div>

Custom Styles

自定义样式

Arbitrary Values

任意值

tsx

<div className="top-[117px]">           {/* Custom top value */}
<div className="bg-[#1da1f2]">          {/* Custom color */}
<div className="grid-cols-[200px_1fr]"> {/* Custom grid template */}

tsx

<div className="top-[117px]">           {/* Custom top value */}
<div className="bg-[#1da1f2]">          {/* Custom color */}
<div className="grid-cols-[200px_1fr]"> {/* Custom grid template */}

@apply Directive

@apply 指令

css

/* components/button.css */
.btn-primary {
  @apply px-4 py-2 bg-blue-600 text-white font-medium rounded-md;
  @apply hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500;
  @apply disabled:opacity-50 disabled:cursor-not-allowed;
}

css

/* components/button.css */
.btn-primary {
  @apply px-4 py-2 bg-blue-600 text-white font-medium rounded-md;
  @apply hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500;
  @apply disabled:opacity-50 disabled:cursor-not-allowed;
}

Configuration

配置

Tailwind v4: CSS-First Configuration

Tailwind v4: CSS优先配置

css

/* app/globals.css */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-900: #1e3a8a;

  /* Custom spacing */
  --spacing-128: 32rem;

  /* Custom fonts */
  --font-family-sans: 'Inter', sans-serif;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;
}

css

/* app/globals.css */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-900: #1e3a8a;

  /* Custom spacing */
  --spacing-128: 32rem;

  /* Custom fonts */
  --font-family-sans: 'Inter', sans-serif;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;
}

Tailwind v3 Config (Still Supported)

Tailwind v3 配置（仍支持）

javascript

// tailwind.config.js (optional in v4)
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          100: '#dbeafe',
          900: '#1e3a8a',
        }
      },
      spacing: {
        '128': '32rem',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
}

javascript

// tailwind.config.js (optional in v4)
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          100: '#dbeafe',
          900: '#1e3a8a',
        }
      },
      spacing: {
        '128': '32rem',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
}

Plugins

插件

Official Plugins

官方插件

bash

npm install @tailwindcss/forms
npm install @tailwindcss/typography
npm install @tailwindcss/aspect-ratio
npm install @tailwindcss/container-queries

tsx

// @tailwindcss/forms
<input type="text" className="form-input rounded-md" />

// @tailwindcss/typography
<article className="prose lg:prose-xl">
  <h1>Article Title</h1>
  <p>Content...</p>
</article>

bash

npm install @tailwindcss/forms
npm install @tailwindcss/typography
npm install @tailwindcss/aspect-ratio
npm install @tailwindcss/container-queries

tsx

// @tailwindcss/forms
<input type="text" className="form-input rounded-md" />

// @tailwindcss/typography
<article className="prose lg:prose-xl">
  <h1>Article Title</h1>
  <p>Content...</p>
</article>

Performance

性能

Automatic Content Detection

自动内容检测

Tailwind v4 automatically detects and scans all template files - no

content

configuration needed.

Tailwind v4 会自动检测并扫描所有模板文件 - 无需配置

content

项。

Build Performance

构建性能

Tailwind v4 delivers 3.5x faster full builds (~100ms) compared to v3 using modern CSS features like

@property

and

color-mix()

Browser Requirements: Safari 16.4+, Chrome 111+, Firefox 128+

Tailwind v4 利用

@property

和

color-mix()

等现代CSS特性，相比v3版本实现了3.5倍的全构建速度提升（约100毫秒）。

浏览器要求：Safari 16.4+、Chrome 111+、Firefox 128+

Common Patterns

常见模式

Centered Content

居中内容

tsx

<div className="flex items-center justify-center min-h-screen">
  <div>Centered content</div>
</div>

tsx

<div className="flex items-center justify-center min-h-screen">
  <div>Centered content</div>
</div>

Sticky Header

粘性头部

tsx

<header className="sticky top-0 z-50 bg-white border-b">
  <nav>Navigation</nav>
</header>

tsx

<header className="sticky top-0 z-50 bg-white border-b">
  <nav>Navigation</nav>
</header>

Grid Layout

网格布局

tsx

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {posts.map(post => (
    <PostCard key={post.id} post={post} />
  ))}
</div>

tsx

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {posts.map(post => (
    <PostCard key={post.id} post={post} />
  ))}
</div>

Truncate Text

文本截断

tsx

<p className="truncate">This text will be truncated with ellipsis if too long</p>
<p className="line-clamp-3">This text will show max 3 lines with ellipsis</p>

tsx

<p className="truncate">This text will be truncated with ellipsis if too long</p>
<p className="line-clamp-3">This text will show max 3 lines with ellipsis</p>

Best Practices

最佳实践

Use Consistent Spacing: Stick to Tailwind's spacing scale
Responsive by Default: Always consider mobile-first design
Extract Components: Avoid repeating long class lists
Use Theme Colors: Define custom colors in config, not arbitrary values
Leverage @apply Sparingly: Prefer utility classes in JSX
Enable Dark Mode: Plan for dark mode from the start
Use Plugins: Leverage official plugins for common needs
Optimize Production: Ensure purge is configured correctly

使用一致间距：遵循Tailwind的间距刻度
默认响应式：始终采用移动优先设计
提取组件：避免重复冗长的类列表
使用主题颜色：在配置中定义自定义颜色，而非使用任意值
谨慎使用@apply：优先在JSX中使用工具类
启用深色模式：从设计初期就考虑深色模式
使用插件：利用官方插件满足常见需求
优化生产环境：确保正确配置清除无用样式

Additional Resources

额外资源

For detailed information, see:

Utility Patterns
Component Library
Configuration Guide

如需详细信息，请查看：

Utility Patterns
Component Library
Configuration Guide