tailwindcss

Tailwind CSS 核心知识

深入了解：使用 mcp__documentation__fetch_docs 并指定技术：tailwindcss，获取全面的文档。

常用工具类

<div class="flex items-center justify-between gap-4">
<div class="grid grid-cols-3 gap-4">
<div class="container mx-auto px-4">


<div class="p-4 m-2 space-y-4">
<div class="px-4 py-2 mt-8 mb-4">


<div class="w-full h-screen max-w-md min-h-[200px]">


<p class="text-lg font-semibold text-gray-900">
<p class="text-sm text-gray-500 leading-relaxed">


<div class="bg-blue-500 text-white border-gray-200">
<div class="bg-gradient-to-r from-blue-500 to-purple-500">

响应式设计

<div class="text-sm md:text-base lg:text-lg">
<div class="flex-col md:flex-row">
<div class="hidden lg:block">

状态

<button class="bg-blue-500 hover:bg-blue-600 active:bg-blue-700">
<input class="border focus:ring-2 focus:ring-blue-500 focus:border-blue-500">


<div class="group">
  <span class="group-hover:text-blue-500">Text</span>
</div>


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">

组件模式

<div class="rounded-lg shadow-md bg-white p-6 hover:shadow-lg transition-shadow">


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


<input class="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">

不适合使用此技能的情况

• 优先使用 CSS-in-JS - 使用 styled-components 或 Emotion
• 传统 CSS 工作流 - 继续使用 SCSS/PostCSS
• 组件库项目 - Material-UI、Ant Design 有各自的样式方案
• 电子邮件模板 - 必须使用内联样式

配置

// tailwind.config.js
export default {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: { brand: '#1a73e8' },
      fontFamily: { sans: ['Inter', 'sans-serif'] }
    }
  },
  plugins: [require('@tailwindcss/forms')]
}

反模式

反模式	不足之处	正确做法
到处使用任意值	难以维护	在主题配置中定义
className 字符串过长	难以阅读	使用 cn() 工具或提取组件
未使用 content 配置	CSS 包体积过大	指定确切的文件路径
在 HTML 中内联 @apply	有悖于工具优先理念	在 CSS 中使用 @apply 或提取组件
忽略清除警告	生产环境中包含未使用的 CSS	修正 content 路径
未使用 CSS 变量	无法动态更改	对可主题化的值使用 CSS 变量

快速故障排除

问题	原因	解决方案
样式未生效	清除过程移除了类	添加到 safelist 或修正 content 路径
暗色模式无效	未设置 darkMode	在配置中设置 darkMode: 'class'
自定义颜色无效	未添加到 theme.extend	添加到 theme.extend.colors
构建体积过大	包含的文件过多	在 content 模式中指定确切的文件
触屏设备上悬停无效	只使用了 :hover	为无障碍访问添加焦点状态
类冲突	存在多个工具类	使用 cn() 和 tailwind-merge

生产环境就绪

性能优化

// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Be specific to avoid scanning node_modules
  ],
  theme: {
    extend: {},
  },
  // Remove unused utilities in production
  safelist: [
    // Only if dynamically generated
    { pattern: /bg-(red|green|blue)-(100|500)/ },
  ],
  // Disable unused core plugins
  corePlugins: {
    preflight: true,
    // container: false, // if not using
  },
};

// postcss.config.js
export default {
  plugins: {
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
    // Production only
    ...(process.env.NODE_ENV === 'production'
      ? { cssnano: { preset: 'default' } }
      : {}),
  },
};

设计系统

// tailwind.config.js
export default {
  theme: {
    // Override defaults
    colors: {
      transparent: 'transparent',
      current: 'currentColor',
      white: '#ffffff',
      black: '#000000',
      // Brand colors
      primary: {
        50: '#eff6ff',
        100: '#dbeafe',
        500: '#3b82f6',
        600: '#2563eb',
        700: '#1d4ed8',
      },
      // Semantic colors
      success: '#22c55e',
      warning: '#f59e0b',
      error: '#ef4444',
    },
    // Consistent spacing scale
    spacing: {
      px: '1px',
      0: '0',
      1: '0.25rem',
      2: '0.5rem',
      3: '0.75rem',
      4: '1rem',
      // ...
    },
    // Typography scale
    fontSize: {
      xs: ['0.75rem', { lineHeight: '1rem' }],
      sm: ['0.875rem', { lineHeight: '1.25rem' }],
      base: ['1rem', { lineHeight: '1.5rem' }],
      lg: ['1.125rem', { lineHeight: '1.75rem' }],
      xl: ['1.25rem', { lineHeight: '1.75rem' }],
    },
  },
};

组件模式

// lib/styles.ts - Reusable class compositions
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Variant patterns with cva
import { cva, type VariantProps } from 'class-variance-authority';

export const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary-600 text-white hover:bg-primary-700',
        outline: 'border border-gray-300 hover:bg-gray-50',
        ghost: 'hover:bg-gray-100',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4',
        lg: 'h-12 px-6 text-lg',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'md',
    },
  }
);

无障碍访问

<button class="focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2">


<a href="#main" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white">
  Skip to content
</a>


<div class="transition-transform motion-reduce:transition-none motion-reduce:transform-none">


<button class="bg-blue-500 forced-colors:bg-[ButtonFace] forced-colors:border forced-colors:border-[ButtonBorder]">

暗色模式

// tailwind.config.js
export default {
  darkMode: 'class', // or 'media'
  // ...
};

// Theme toggle component
function ThemeToggle() {
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    document.documentElement.classList.toggle('dark', theme === 'dark');
  }, [theme]);

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle theme
    </button>
  );
}

测试

// Visual regression testing
import { test, expect } from '@playwright/test';

test('button variants render correctly', async ({ page }) => {
  await page.goto('/storybook/button');

  // Screenshot comparison
  await expect(page.locator('.button-primary')).toHaveScreenshot('button-primary.png');
  await expect(page.locator('.button-outline')).toHaveScreenshot('button-outline.png');
});

// Unit testing class compositions
import { cn, buttonVariants } from '@/lib/styles';

describe('buttonVariants', () => {
  it('generates correct classes for default variant', () => {
    const classes = buttonVariants({ variant: 'default', size: 'md' });
    expect(classes).toContain('bg-primary-600');
    expect(classes).toContain('h-10');
  });
});

监控指标

指标	目标
CSS 包体积	< 30KB gzip 压缩后
未使用的 CSS	0%
首次内容绘制	< 1s
Lighthouse 性能评分	> 90

检查清单

• 正确配置 content 路径
• 生产环境使用带有 cssnano 的 PostCSS
• 设计令牌（颜色、间距、排版）
• 用于合并类的 cn() 工具
• 用于组件变体的 CVA
• 支持暗色模式
• 为无障碍访问使用 focus-visible
• 支持减少动态效果
• 监控包体积
• 视觉回归测试

参考文档

• 工具类速查表
• 响应式模式