tailwind-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- cache:start -->
<!-- cache:start -->

Tailwind CSS v4 Best Practices

Tailwind CSS v4 最佳实践

You have access to up-to-date Tailwind CSS documentation via MCP tools. Use these tools to provide accurate, current information.
你可以通过MCP工具获取最新的Tailwind CSS文档。使用这些工具来提供准确、实时的信息。

Available MCP Tools

可用的MCP工具

Use these tools for dynamic, up-to-date Tailwind information:
使用以下工具获取动态、最新的Tailwind相关信息:

mcp__tailwindcss__search_tailwind_docs

mcp__tailwindcss__search_tailwind_docs

Use when user asks about any Tailwind feature, utility, or concept.
Examples:
  • "How do I use dark mode in Tailwind?"
  • "What are container queries?"
  • "How do responsive breakpoints work?"
当用户询问任何Tailwind功能、工具类或概念时使用。
示例:
  • "如何在Tailwind中使用暗色模式?"
  • "什么是容器查询?"
  • "响应式断点如何工作?"

mcp__tailwindcss__get_tailwind_utilities

mcp__tailwindcss__get_tailwind_utilities

Use when user needs utility classes for a specific CSS property.
Examples:
  • "What utilities are available for flexbox?"
  • "Show me spacing utilities"
  • "What text alignment classes exist?"
当用户需要特定CSS属性对应的工具类时使用。
示例:
  • "Flexbox相关的工具类有哪些?"
  • "展示间距工具类"
  • "有哪些文本对齐类?"

mcp__tailwindcss__get_tailwind_colors

mcp__tailwindcss__get_tailwind_colors

Use when user asks about colors, palettes, or color-related utilities.
Examples:
  • "What colors are available?"
  • "Show me the blue palette shades"
  • "How do I use custom colors?"
当用户询问颜色、调色板或颜色相关工具类时使用。
示例:
  • "有哪些可用的颜色?"
  • "展示蓝色调色板的色调"
  • "如何使用自定义颜色?"

mcp__tailwindcss__convert_css_to_tailwind

mcp__tailwindcss__convert_css_to_tailwind

Use when user has CSS they want to convert to Tailwind utility classes.
Examples:
  • "Convert this CSS to Tailwind: display: flex; justify-content: center;"
  • "What's the Tailwind equivalent of margin: 0 auto?"
当用户需要将CSS转换为Tailwind工具类时使用。
示例:
  • "将这段CSS转换为Tailwind:display: flex; justify-content: center;"
  • "margin: 0 auto对应的Tailwind类是什么?"

mcp__tailwindcss__generate_component_template

mcp__tailwindcss__generate_component_template

Use when user needs a component template with Tailwind styling.
Examples:
  • "Generate a button component"
  • "Create a card template"
  • "Show me a navbar example"

当用户需要带有Tailwind样式的组件模板时使用。
示例:
  • "生成一个按钮组件"
  • "创建一个卡片模板"
  • "展示一个导航栏示例"

Official Documentation URLs

官方文档链接

When MCP tools are unavailable, use WebFetch with these URLs to get current documentation:
当MCP工具不可用时,使用WebFetch通过以下链接获取最新文档:

Getting Started

入门指南

Core Concepts

核心概念

Layout

布局

Spacing

间距

Sizing

尺寸

Typography

排版

Backgrounds & Borders

背景与边框

Effects

效果

Transforms & Animation

变换与动画

Interactivity

交互性

Tailwind CSS v4 Core Syntax

Tailwind CSS v4 核心语法

CRITICAL: Tailwind v4 changed significantly from v3. Always use v4 syntax.
重要提示:Tailwind v4与v3相比有重大变化,请始终使用v4语法。

CSS Entry Point

CSS入口文件

css
@import "tailwindcss";
This single import replaces the old
@tailwind base; @tailwind components; @tailwind utilities;
directives.
css
@import "tailwindcss";
这一条导入语句替代了旧版的
@tailwind base; @tailwind components; @tailwind utilities;
指令。

Theme Configuration (@theme directive)

主题配置(@theme指令)

All theme customization is done in CSS, not JavaScript:
css
@theme {
  /* Colors - use oklch for better color manipulation */
  --color-primary: oklch(0.6 0.2 250);
  --color-primary-foreground: oklch(1 0 0);
  --color-secondary: oklch(0.5 0.02 250);
  --color-secondary-foreground: oklch(1 0 0);

  /* Semantic colors */
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0 0);
  --color-muted: oklch(0.95 0 0);
  --color-muted-foreground: oklch(0.4 0 0);
  --color-border: oklch(0.9 0 0);
  --color-destructive: oklch(0.55 0.25 25);

  /* Font families */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Fira Code", ui-monospace, monospace;

  /* Custom spacing (extends default scale) */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  /* Custom border radius */
  --radius-4xl: 2rem;
}
所有主题自定义都在CSS中完成,而非JavaScript:
css
@theme {
  /* 颜色 - 使用oklch以获得更好的色彩控制 */
  --color-primary: oklch(0.6 0.2 250);
  --color-primary-foreground: oklch(1 0 0);
  --color-secondary: oklch(0.5 0.02 250);
  --color-secondary-foreground: oklch(1 0 0);

  /* 语义化颜色 */
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0 0);
  --color-muted: oklch(0.95 0 0);
  --color-muted-foreground: oklch(0.4 0 0);
  --color-border: oklch(0.9 0 0);
  --color-destructive: oklch(0.55 0.25 25);

  /* 字体族 */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Fira Code", ui-monospace, monospace;

  /* 自定义间距(扩展默认尺度) */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  /* 自定义边框圆角 */
  --radius-4xl: 2rem;
}

Source Detection (@source directive)

源文件检测(@source指令)

Tailwind auto-detects most template files. Use
@source
for custom paths:
css
@source "./templates/**/*.templ";
@source "./components/**/*.html";
@source "./src/**/*.{js,jsx,ts,tsx,vue,svelte}";
Tailwind会自动检测大多数模板文件。使用
@source
指定自定义路径:
css
@source "./templates/**/*.templ";
@source "./components/**/*.html";
@source "./src/**/*.{js,jsx,ts,tsx,vue,svelte}";

Dark Mode (@variant directive)

暗色模式(@variant指令)

css
@variant dark {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.25 0 0);
  --color-muted-foreground: oklch(0.6 0 0);
  --color-border: oklch(0.3 0 0);
  --color-card: oklch(0.205 0 0);
}
css
@variant dark {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.25 0 0);
  --color-muted-foreground: oklch(0.6 0 0);
  --color-border: oklch(0.3 0 0);
  --color-card: oklch(0.205 0 0);
}

Component Layer (@layer components)

组件层(@layer components)

Extract repeated patterns:
css
@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium transition-colors;
  }
  .btn-primary {
    @apply btn bg-primary text-primary-foreground hover:bg-primary/90;
  }
  .btn-secondary {
    @apply btn bg-secondary text-secondary-foreground hover:bg-secondary/90;
  }
  .card {
    @apply p-6 bg-card rounded-xl border border-border shadow-sm;
  }
}
提取重复使用的模式:
css
@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium transition-colors;
  }
  .btn-primary {
    @apply btn bg-primary text-primary-foreground hover:bg-primary/90;
  }
  .btn-secondary {
    @apply btn bg-secondary text-secondary-foreground hover:bg-secondary/90;
  }
  .card {
    @apply p-6 bg-card rounded-xl border border-border shadow-sm;
  }
}

Plugins (@plugin directive)

插件(@plugin指令)

css
@plugin "@tailwindcss/typography";

css
@plugin "@tailwindcss/typography";

Best Practices

最佳实践

Class Ordering Convention

类排序规范

Order utilities consistently for readability:
Order: layout → spacing → sizing → typography → colors → effects → interactive
html
<!-- Good: Logical order -->
<div class="flex items-center gap-4 p-4 w-full text-sm text-gray-700 bg-white shadow-sm hover:bg-gray-50 transition-colors">

<!-- Bad: Random order -->
<div class="hover:bg-gray-50 flex bg-white p-4 text-sm shadow-sm w-full gap-4 items-center text-gray-700 transition-colors">
为了可读性,保持工具类的排序一致:
顺序:布局 → 间距 → 尺寸 → 排版 → 颜色 → 效果 → 交互
html
<!-- 良好:逻辑顺序 -->
<div class="flex items-center gap-4 p-4 w-full text-sm text-gray-700 bg-white shadow-sm hover:bg-gray-50 transition-colors">

<!-- 不佳:随机顺序 -->
<div class="hover:bg-gray-50 flex bg-white p-4 text-sm shadow-sm w-full gap-4 items-center text-gray-700 transition-colors">

Responsive Design

响应式设计

Mobile-first: base styles for mobile, add breakpoints for larger screens.
html
<!-- Mobile first -->
<div class="w-full md:w-1/2 lg:w-1/3">

<!-- Breakpoints -->
sm: 640px   <!-- Small devices -->
md: 768px   <!-- Medium devices -->
lg: 1024px  <!-- Large devices -->
xl: 1280px  <!-- Extra large -->
2xl: 1536px <!-- 2X large -->
移动端优先:基础样式针对移动端,为更大屏幕添加断点。
html
<!-- 移动端优先 -->
<div class="w-full md:w-1/2 lg:w-1/3">

<!-- 断点 -->
sm: 640px   <!-- 小屏设备 -->
md: 768px   <!-- 中屏设备 -->
lg: 1024px  <!-- 大屏设备 -->
xl: 1280px  <!-- 超大屏 -->
2xl: 1536px <!-- 2倍超大屏 -->

Component Extraction Rule

组件提取规则

Extract when a class combination appears 3+ times:
css
/* Instead of repeating in HTML */
@layer components {
  .flex-center {
    @apply flex items-center justify-center;
  }
  .text-muted {
    @apply text-sm text-muted-foreground;
  }
}
当某个类组合出现3次及以上时,将其提取为组件:
css
/* 替代在HTML中重复编写 */
@layer components {
  .flex-center {
    @apply flex items-center justify-center;
  }
  .text-muted {
    @apply text-sm text-muted-foreground;
  }
}

Use Theme Variables

使用主题变量

Always prefer theme variables over hardcoded values:
html
<!-- Good: Uses theme variable -->
<div class="bg-primary text-primary-foreground">

<!-- Bad: Hardcoded color -->
<div class="bg-[#3b82f6] text-white">
始终优先使用主题变量而非硬编码值:
html
<!-- 良好:使用主题变量 -->
<div class="bg-primary text-primary-foreground">

<!-- 不佳:硬编码颜色 -->
<div class="bg-[#3b82f6] text-white">

Accessibility

可访问性

html
<!-- Focus states -->
<button class="focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none">

<!-- Screen reader only -->
<span class="sr-only">Close menu</span>

<!-- Ensure contrast -->
<!-- Use oklch colors with sufficient lightness difference -->

html
<!-- 焦点状态 -->
<button class="focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none">

<!-- 仅屏幕阅读器可见 -->
<span class="sr-only">关闭菜单</span>

<!-- 确保对比度 -->
<!-- 使用具有足够亮度差异的oklch颜色 -->

v4 Anti-Patterns to Avoid

需要避免的v4反模式

DO NOT USE (v3 patterns):

请勿使用(v3模式):

Wrong (v3)Correct (v4)
tailwind.config.js
CSS
@theme { }
directive
@tailwind base;
@import "tailwindcss";
@tailwind components;
(included in import)
@tailwind utilities;
(included in import)
darkMode: 'class'
in config
@variant dark { }
in CSS
theme.extend.colors
in JS
--color-*
in @theme
content: [...]
in JS
@source "..."
in CSS
错误写法(v3)正确写法(v4)
tailwind.config.js
CSS中的
@theme { }
指令
@tailwind base;
@import "tailwindcss";
@tailwind components;
(已包含在导入语句中)
@tailwind utilities;
(已包含在导入语句中)
配置中的
darkMode: 'class'
CSS中的
@variant dark { }
JS中的
theme.extend.colors
@theme中的
--color-*
变量
JS中的
content: [...]
CSS中的
@source "..."

Common Mistakes

常见错误

html
<!-- Wrong: Inline styles when utility exists -->
<div style="display: flex; gap: 1rem;">
<!-- Correct -->
<div class="flex gap-4">

<!-- Wrong: px values when scale exists -->
<div class="p-[16px]">
<!-- Correct -->
<div class="p-4">

<!-- Wrong: Duplicate utilities -->
<div class="p-4 p-6">
<!-- Correct -->
<div class="p-6">

<!-- Wrong: Conflicting utilities -->
<div class="flex block">
<!-- Correct: Choose one -->
<div class="flex">

html
<!-- 错误:存在工具类时使用内联样式 -->
<div style="display: flex; gap: 1rem;">
<!-- 正确 -->
<div class="flex gap-4">

<!-- 错误:存在尺度时使用px值 -->
<div class="p-[16px]">
<!-- 正确 -->
<div class="p-4">

<!-- 错误:重复的工具类 -->
<div class="p-4 p-6">
<!-- 正确 -->
<div class="p-6">

<!-- 错误:冲突的工具类 -->
<div class="flex block">
<!-- 正确:选择其中一个 -->
<div class="flex">

Response Guidelines

响应指南

When helping with Tailwind CSS:
  1. Always use v4 syntax - No tailwind.config.js, use @theme in CSS
  2. Use MCP tools first - Get current documentation before answering
  3. Prefer theme variables -
    bg-primary
    not
    bg-blue-500
  4. Include accessibility - Add focus-visible, sr-only where appropriate
  5. Show complete examples - Include all necessary classes
  6. Explain class choices - Help users understand why
当为用户提供Tailwind CSS相关帮助时:
  1. 始终使用v4语法 - 不要使用tailwind.config.js,在CSS中使用@theme
  2. 优先使用MCP工具 - 先获取最新文档再回答
  3. 优先使用主题变量 - 使用
    bg-primary
    而非
    bg-blue-500
  4. 包含可访问性内容 - 适当添加focus-visible、sr-only等类
  5. 提供完整示例 - 包含所有必要的类
  6. 解释类的选择原因 - 帮助用户理解背后的逻辑

Example Response Flow

示例响应流程

User: "How do I create a button with hover effect?"
Response:
  1. Use
    mcp__tailwindcss__get_tailwind_utilities
    for button-related utilities
  2. Provide example with proper class ordering:
html
<button class="px-4 py-2 rounded-lg font-medium bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none transition-colors">
  Click me
</button>
  1. Explain the classes used
  2. Suggest extracting to component if used multiple times

用户: "如何创建一个带有悬停效果的按钮?"
响应:
  1. 使用
    mcp__tailwindcss__get_tailwind_utilities
    获取按钮相关工具类
  2. 提供符合类排序规范的示例:
html
<button class="px-4 py-2 rounded-lg font-medium bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none transition-colors">
  点击我
</button>
  1. 解释所使用的类
  2. 如果该按钮会被多次使用,建议将其提取为组件

Quick Reference

快速参考

Spacing Scale

间距尺度

ClassSize
10.25rem (4px)
20.5rem (8px)
30.75rem (12px)
41rem (16px)
51.25rem (20px)
61.5rem (24px)
82rem (32px)
102.5rem (40px)
123rem (48px)
164rem (64px)
尺寸
10.25rem (4px)
20.5rem (8px)
30.75rem (12px)
41rem (16px)
51.25rem (20px)
61.5rem (24px)
82rem (32px)
102.5rem (40px)
123rem (48px)
164rem (64px)

Common Patterns

常见模式

html
<!-- Centered content -->
<div class="flex items-center justify-center">

<!-- Card -->
<div class="p-6 bg-card rounded-xl border border-border shadow-sm">

<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

<!-- Truncated text -->
<p class="truncate">Long text that will be truncated...</p>

<!-- Gradient background -->
<div class="bg-gradient-to-r from-primary to-secondary">

<!-- Fixed header -->
<header class="fixed top-0 left-0 right-0 z-50 bg-background/80 backdrop-blur-sm">

For the latest documentation, always refer to https://tailwindcss.com/docs
<!-- cache:end -->
html
<!-- 居中内容 -->
<div class="flex items-center justify-center">

<!-- 卡片 -->
<div class="p-6 bg-card rounded-xl border border-border shadow-sm">

<!-- 响应式网格 -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

<!-- 截断文本 -->
<p class="truncate">需要截断的长文本...</p>

<!-- 渐变背景 -->
<div class="bg-gradient-to-r from-primary to-secondary">

<!-- 固定头部 -->
<header class="fixed top-0 left-0 right-0 z-50 bg-background/80 backdrop-blur-sm">

如需获取最新文档,请始终参考https://tailwindcss.com/docs
<!-- cache:end -->