tailwind-best-practices

Tailwind CSS 最佳实践

使用 Tailwind CSS v3.4+ 和 v4 构建一致且易于维护的界面的全面模式。包含 29 条规则，涵盖响应式设计、暗色模式、组件模式、配置和 v4 迁移。

元数据

• 版本： 1.0.0
• 框架： Tailwind CSS v3.4+ / v4.0+
• 规则数量： 8 个类别，共 29 条规则
• 许可证： MIT
• 文档： tailwindcss.com/docs

步骤 1：检测 Tailwind 版本

给出任何建议前，务必先检查版本。 v3 和 v4 有本质区别。

检查 package.json 中安装的版本：

{ "tailwindcss": "^3.x" }  // → v3 rules apply
{ "tailwindcss": "^4.x" }  // → v4 rules apply

还要检查以下特征：

特征	版本
存在 tailwind.config.js	v3
CSS 中有 @import "tailwindcss"	v4
依赖项中有 @tailwindcss/vite	v4
依赖项中有 @tailwindcss/postcss	v4
CSS 中有 @theme {} 块	v4

如果是 v3：应用 resp-、dark-、comp-、config- 规则。请注意，v4 已可用。 如果是 v4：应用 v4- 规则。tailwind.config.js 模式不适用，请改用 @theme {}。 如果从 v3 迁移到 v4：直接遵循 v4-migration 规则。

适用场景

在以下情况下，请参考这些指南：

• 编写响应式布局
• 实现暗色模式
• 创建可复用的组件样式
• 配置 Tailwind（v3 或 v4）
• 将项目从 v3 迁移到 v4
• 使用 v4 搭建新项目

按优先级划分的规则类别

优先级	类别	影响	前缀	版本
1	响应式设计	严重	resp-	v3 / v4
2	暗色模式	严重	dark-	v3 / v4
3	组件模式	高	comp-	v3 / v4
4	自定义配置	高	config-	v3
5	V4 与迁移	高	v4-	仅 v4
6	间距与排版	中	space-	v3 / v4
7	动画	中	anim-	v3 / v4
8	性能	低	perf-	v3 / v4

快速参考

1. 响应式设计（严重）

• resp-mobile-first - 移动优先方法
• resp-breakpoints - 正确使用断点
• resp-container - 容器模式
• resp-grid-flex - Grid 与 Flexbox 的选择
• resp-hidden-shown - 条件显示

2. 暗色模式（严重）

• dark-setup - 配置暗色模式
• dark-classes - 应用暗色模式类
• dark-toggle - 实现暗色模式切换
• dark-system-preference - 遵循系统偏好设置
• dark-colors - 同时为两种模式设计

3. 组件模式（高）

• comp-clsx-cn - 条件类工具
• comp-variants - 组件变体模式
• comp-slots - 基于插槽的组件
• comp-composition - 组合工具类

4. 自定义配置 — 仅 v3（高）

• config-extend - 扩展还是覆盖主题
• config-colors - 自定义调色板
• config-fonts - 自定义字体
• config-screens - 自定义断点
• config-plugins - 使用插件

5. V4 与迁移（高）

• v4-installation - 使用 Vite 或 PostCSS 安装 v4，配置 @source、@reference
• v4-theme-configuration - 在 CSS 中使用 @theme {} 替代 tailwind.config.js
• v4-custom-utilities - @utility、@custom-variant、@variant、@plugin
• v4-migration - v3 → v4 逐步迁移，涵盖重命名的工具类、starting:、forced-colors:

6. 间距与排版（中）

• space-consistent - 一致的间距刻度
• space-margins - 外边距模式
• space-padding - 内边距模式
• typo-scale - 排版刻度
• typo-line-height - 行高

7. 动画（中）

• anim-transitions - 过渡工具类
• anim-keyframes - 自定义关键帧
• anim-reduced-motion - 遵循动态效果偏好设置

8. 性能（低）

• perf-purge - 内容配置
• perf-jit - JIT 模式的优势
• perf-arbitrary - 任意值的使用

基本模式

移动优先的响应式设计

// ✅ Mobile-first: start with mobile, add larger breakpoints
<div className="
  w-full           // Mobile: full width
  md:w-1/2         // Tablet: half width
  lg:w-1/3         // Desktop: third width
">
  <p className="
    text-sm          // Mobile: small text
    md:text-base     // Tablet: base text
    lg:text-lg       // Desktop: large text
  ">
    Content
  </p>
</div>

// ❌ Don't think desktop-first
<div className="w-1/3 md:w-1/2 sm:w-full">  // Confusing

深色模式实现

v3 — tailwind.config.js：

module.exports = { darkMode: 'class' }

v4 — 仅使用 CSS，无配置文件：

@import "tailwindcss";
/* dark mode is class-based by default in v4 — no config needed */

组件 — 两个版本完全相同：

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  <h2 className="text-gray-900 dark:text-white">Title</h2>
  <p className="text-gray-600 dark:text-gray-400">Description</p>
</div>

function toggleDarkMode() {
  document.documentElement.classList.toggle('dark')
}

使用 clsx/cn 实现条件类

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

// cn utility - merges Tailwind classes intelligently
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

// Usage
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  className?: string
  children: React.ReactNode
}

function Button({ variant = 'primary', size = 'md', className, children }: ButtonProps) {
  return (
    <button
      className={cn(
        // Base styles
        'inline-flex items-center justify-center rounded-md font-medium transition-colors',
        'focus:outline-none focus:ring-2 focus:ring-offset-2',

        // Variants
        {
          'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500':
            variant === 'primary',
          'bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-500':
            variant === 'secondary',
          'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500':
            variant === 'danger',
        },

        // Sizes
        {
          'px-3 py-1.5 text-sm': size === 'sm',
          'px-4 py-2 text-base': size === 'md',
          'px-6 py-3 text-lg': size === 'lg',
        },

        // Allow override
        className
      )}
    >
      {children}
    </button>
  )
}

主题配置 — v3 与 v4

v3 — tailwind.config.js：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./resources/**/*.{blade.php,js,ts,jsx,tsx}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: { primary: { 500: '#0ea5e9', 600: '#0284c7' } },
      fontFamily: { sans: ['Inter', 'sans-serif'] },
      spacing: { '18': '4.5rem' },
    },
  },
  plugins: [require('@tailwindcss/forms')],
}

v4 — 仅使用 app.css，无需 JS 配置：

@import "tailwindcss";

@theme {
  --color-primary-500: #0ea5e9;
  --color-primary-600: #0284c7;
  --font-sans: Inter, sans-serif;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 1920px;
}

如需了解完整详情，请参阅 v4-theme-configuration 和 v4-migration 规则。

响应式网格布局

// Product grid - responsive columns
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
  {products.map(product => (
    <ProductCard key={product.id} product={product} />
  ))}
</div>

// Dashboard layout - sidebar + main
<div className="flex flex-col lg:flex-row min-h-screen">
  <aside className="
    w-full lg:w-64
    bg-gray-900
    lg:min-h-screen
  ">
    <nav>...</nav>
  </aside>
  <main className="flex-1 p-4 lg:p-8">
    <div className="max-w-7xl mx-auto">
      {children}
    </div>
  </main>
</div>

表单样式

<form className="space-y-6">
  <div>
    <label htmlFor="email" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
      Email
    </label>
    <input
      type="email"
      id="email"
      className="
        mt-1 block w-full rounded-md
        border-gray-300 dark:border-gray-600
        bg-white dark:bg-gray-800
        text-gray-900 dark:text-white
        shadow-sm
        focus:border-blue-500 focus:ring-blue-500
        disabled:bg-gray-100 disabled:cursor-not-allowed
      "
    />
  </div>

  <button
    type="submit"
    className="
      w-full flex justify-center
      py-2 px-4
      border border-transparent rounded-md
      shadow-sm text-sm font-medium
      text-white bg-blue-600
      hover:bg-blue-700
      focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500
      disabled:opacity-50 disabled:cursor-not-allowed
    "
  >
    Submit
  </button>
</form>

支持减少动态效果的动画

// Respect user's motion preferences
<div className="
  transition-transform duration-300
  hover:scale-105
  motion-reduce:transition-none
  motion-reduce:hover:transform-none
">
  Card content
</div>

// Custom animation
<div className="animate-fade-in motion-reduce:animate-none">
  Content
</div>

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      keyframes: {
        'fade-in': {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
      },
      animation: {
        'fade-in': 'fade-in 0.3s ease-out',
      },
    },
  },
}

使用方法

始终先运行步骤 1（版本检测），然后阅读相关规则文件：

v3 项目：

rules/config-extend-theme.md
rules/dark-setup.md
rules/comp-clsx-cn.md
rules/resp-mobile-first.md

v4 项目：

rules/v4-installation.md
rules/v4-theme-configuration.md
rules/v4-custom-utilities.md

从 v3 迁移到 v4：

rules/v4-migration.md

参考资料

• Tailwind CSS 文档 - 官方文档
• 响应式设计指南 - 移动优先模式
• 深色模式指南 - 主题实现
• 配置指南 - 自定义
• Tailwind UI - 官方组件库
• Headless UI - 无障碍组件
• Heroicons - 图标库

生态工具

• Tailwind CSS IntelliSense - VS Code 自动补全和代码检查
• Prettier Plugin - 自动排序类名
• tailwind-merge - 无冲突地合并类名
• clsx - 条件类工具
• CVA - 组件变体系统

许可证

MIT 许可证 - 完整许可证文本请参阅仓库。

此技能是 Agent Skills 集合的一部分，旨在依据行业最佳实践提供 AI 驱动的开发辅助。