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_docsmcp__tailwindcss__search_tailwind_docs
mcp__tailwindcss__search_tailwind_docsUse 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_utilitiesmcp__tailwindcss__get_tailwind_utilities
mcp__tailwindcss__get_tailwind_utilitiesUse 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_colorsmcp__tailwindcss__get_tailwind_colors
mcp__tailwindcss__get_tailwind_colorsUse 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_tailwindmcp__tailwindcss__convert_css_to_tailwind
mcp__tailwindcss__convert_css_to_tailwindUse 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_templatemcp__tailwindcss__generate_component_template
mcp__tailwindcss__generate_component_templateUse 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
入门指南
| Topic | URL |
|---|---|
| Installation | https://tailwindcss.com/docs/installation |
| Using Vite | https://tailwindcss.com/docs/installation/using-vite |
| Using PostCSS | https://tailwindcss.com/docs/installation/using-postcss |
| Tailwind CLI | https://tailwindcss.com/docs/installation/tailwind-cli |
| Editor Setup | https://tailwindcss.com/docs/editor-setup |
| Upgrade Guide | https://tailwindcss.com/docs/upgrade-guide |
Core Concepts
核心概念
| Topic | URL |
|---|---|
| Utility Classes | https://tailwindcss.com/docs/styling-with-utility-classes |
| Hover, Focus, States | https://tailwindcss.com/docs/hover-focus-and-other-states |
| Responsive Design | https://tailwindcss.com/docs/responsive-design |
| Dark Mode | https://tailwindcss.com/docs/dark-mode |
| Theme Variables | https://tailwindcss.com/docs/theme |
| Colors | https://tailwindcss.com/docs/colors |
| Custom Styles | https://tailwindcss.com/docs/adding-custom-styles |
| Functions & Directives | https://tailwindcss.com/docs/functions-and-directives |
Layout
布局
Spacing
间距
| Topic | URL |
|---|---|
| Padding | https://tailwindcss.com/docs/padding |
| Margin | https://tailwindcss.com/docs/margin |
| Space Between | https://tailwindcss.com/docs/space |
Sizing
尺寸
| Topic | URL |
|---|---|
| Width | https://tailwindcss.com/docs/width |
| Height | https://tailwindcss.com/docs/height |
| Min/Max Width | https://tailwindcss.com/docs/min-width |
| Min/Max Height | https://tailwindcss.com/docs/min-height |
Typography
排版
| Topic | URL |
|---|---|
| Font Family | https://tailwindcss.com/docs/font-family |
| Font Size | https://tailwindcss.com/docs/font-size |
| Font Weight | https://tailwindcss.com/docs/font-weight |
| Line Height | https://tailwindcss.com/docs/line-height |
| Text Color | https://tailwindcss.com/docs/text-color |
| Text Align | https://tailwindcss.com/docs/text-align |
Backgrounds & Borders
背景与边框
| Topic | URL |
|---|---|
| Background Color | https://tailwindcss.com/docs/background-color |
| Background Image | https://tailwindcss.com/docs/background-image |
| Border Radius | https://tailwindcss.com/docs/border-radius |
| Border Width | https://tailwindcss.com/docs/border-width |
| Border Color | https://tailwindcss.com/docs/border-color |
| Box Shadow | https://tailwindcss.com/docs/box-shadow |
Effects
效果
Transforms & Animation
变换与动画
Interactivity
交互性
| Topic | URL |
|---|---|
| Cursor | https://tailwindcss.com/docs/cursor |
| User Select | https://tailwindcss.com/docs/user-select |
| Scroll Behavior | https://tailwindcss.com/docs/scroll-behavior |
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 directives.
@tailwind base; @tailwind components; @tailwind utilities;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 for custom paths:
@sourcecss
@source "./templates/**/*.templ";
@source "./components/**/*.html";
@source "./src/**/*.{js,jsx,ts,tsx,vue,svelte}";Tailwind会自动检测大多数模板文件。使用指定自定义路径:
@sourcecss
@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) |
|---|---|
| CSS |
| |
| (included in import) |
| (included in import) |
| |
| |
| |
| 错误写法(v3) | 正确写法(v4) |
|---|---|
| CSS中的 |
| |
| (已包含在导入语句中) |
| (已包含在导入语句中) |
配置中的 | CSS中的 |
JS中的 | @theme中的 |
JS中的 | CSS中的 |
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:
- Always use v4 syntax - No tailwind.config.js, use @theme in CSS
- Use MCP tools first - Get current documentation before answering
- Prefer theme variables - not
bg-primarybg-blue-500 - Include accessibility - Add focus-visible, sr-only where appropriate
- Show complete examples - Include all necessary classes
- Explain class choices - Help users understand why
当为用户提供Tailwind CSS相关帮助时:
- 始终使用v4语法 - 不要使用tailwind.config.js,在CSS中使用@theme
- 优先使用MCP工具 - 先获取最新文档再回答
- 优先使用主题变量 - 使用而非
bg-primarybg-blue-500 - 包含可访问性内容 - 适当添加focus-visible、sr-only等类
- 提供完整示例 - 包含所有必要的类
- 解释类的选择原因 - 帮助用户理解背后的逻辑
Example Response Flow
示例响应流程
User: "How do I create a button with hover effect?"
Response:
- Use for button-related utilities
mcp__tailwindcss__get_tailwind_utilities - 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>- Explain the classes used
- Suggest extracting to component if used multiple times
用户: "如何创建一个带有悬停效果的按钮?"
响应:
- 使用获取按钮相关工具类
mcp__tailwindcss__get_tailwind_utilities - 提供符合类排序规范的示例:
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>- 解释所使用的类
- 如果该按钮会被多次使用,建议将其提取为组件
Quick Reference
快速参考
Spacing Scale
间距尺度
| Class | Size |
|---|---|
| 1 | 0.25rem (4px) |
| 2 | 0.5rem (8px) |
| 3 | 0.75rem (12px) |
| 4 | 1rem (16px) |
| 5 | 1.25rem (20px) |
| 6 | 1.5rem (24px) |
| 8 | 2rem (32px) |
| 10 | 2.5rem (40px) |
| 12 | 3rem (48px) |
| 16 | 4rem (64px) |
| 类 | 尺寸 |
|---|---|
| 1 | 0.25rem (4px) |
| 2 | 0.5rem (8px) |
| 3 | 0.75rem (12px) |
| 4 | 1rem (16px) |
| 5 | 1.25rem (20px) |
| 6 | 1.5rem (24px) |
| 8 | 2rem (32px) |
| 10 | 2.5rem (40px) |
| 12 | 3rem (48px) |
| 16 | 4rem (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 -->