Back to Details

tailwind-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tailwind CSS Configuration Skill

Tailwind CSS 配置技能指南

Configuration Structure

配置结构

packages/ui/
├── tailwind.config.ts       # Base config with shadcn/ui theming
└── src/styles/globals.css   # CSS variables

apps/web/
├── tailwind.config.ts       # Extends UI package config
└── src/app/globals.css      # App-specific styles
packages/ui/
├── tailwind.config.ts       # Base config with shadcn/ui theming
└── src/styles/globals.css   # CSS variables
apps/web/ ├── tailwind.config.ts # Extends UI package config └── src/app/globals.css # App-specific styles

CSS Variables

CSS 变量

Defined in 
packages/ui/src/styles/globals.css
:
css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --muted: 210 40% 96.1%;
    --accent: 210 40% 96.1%;
    --destructive: 0 84.2% 60.2%;
    --border: 214.3 31.8% 91.4%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode values */
  }
}
定义于
packages/ui/src/styles/globals.css
中：
css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --muted: 210 40% 96.1%;
    --accent: 210 40% 96.1%;
    --destructive: 0 84.2% 60.2%;
    --border: 214.3 31.8% 91.4%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode values */
  }
}

Adding Custom Colors

添加自定义颜色

typescript
// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          primary: "#0070F3",
          secondary: "#7928CA",
        },
      },
    },
  },
};
typescript
// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          primary: "#0070F3",
          secondary: "#7928CA",
        },
      },
    },
  },
};

Adding Animations

添加动画

typescript
theme: {
  extend: {
    keyframes: {
      shimmer: {
        "0%": { backgroundPosition: "-200% 0" },
        "100%": { backgroundPosition: "200% 0" },
      },
    },
    animation: {
      shimmer: "shimmer 2s linear infinite",
    },
  },
}
typescript
theme: {
  extend: {
    keyframes: {
      shimmer: {
        "0%": { backgroundPosition: "-200% 0" },
        "100%": { backgroundPosition: "200% 0" },
      },
    },
    animation: {
      shimmer: "shimmer 2s linear infinite",
    },
  },
}

Custom Utilities

自定义工具类

css
/* globals.css */
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
  .scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
}
css
/* globals.css */
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
  .scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
}

Plugins

插件

typescript
plugins: [
  require("@tailwindcss/typography"),  // prose classes
  require("@tailwindcss/forms"),        // form resets
  require("tailwindcss-animate"),       // animations
]
typescript
plugins: [
  require("@tailwindcss/typography"),  // prose classes
  require("@tailwindcss/forms"),        // form resets
  require("tailwindcss-animate"),       // animations
]

Size Utility Convention

尺寸工具类约定

Use 
size-*
instead of 
h-* w-*
for equal dimensions:
tsx
// ✅ Good
<div className="size-4">Icon</div>
<div className="size-8">Avatar</div>

// ❌ Avoid
<div className="h-4 w-4">Icon</div>
使用
size-*
替代
h-* w-*
来设置等宽高的元素：
tsx
// ✅ Good
<div className="size-4">Icon</div>
<div className="size-8">Avatar</div>

// ❌ Avoid
<div className="h-4 w-4">Icon</div>

Dark Mode

暗色模式

typescript
// tailwind.config.ts
export default {
  darkMode: ["class"],
};
Toggle with next-themes:
tsx
import { useTheme } from "next-themes";
const { theme, setTheme } = useTheme();
typescript
// tailwind.config.ts
export default {
  darkMode: ["class"],
};
使用next-themes切换：
tsx
import { useTheme } from "next-themes";
const { theme, setTheme } = useTheme();

Debugging

调试

bash
undefined
bash
undefined

Check resolved config

Check resolved config

npx tailwindcss config
npx tailwindcss config

Watch for generated classes

Watch for generated classes

TAILWIND_MODE=watch npx tailwindcss -i ./src/styles/globals.css -o ./dist/output.css --watch

**Common issues:**
- Classes not applying → Check content paths
- Dark mode not working → Verify `darkMode: ["class"]` and ThemeProvider
- Classes purged → Add to safelist or use complete class names
TAILWIND_MODE=watch npx tailwindcss -i ./src/styles/globals.css -o ./dist/output.css --watch

**常见问题：**
- 类未生效 → 检查内容路径
- 暗色模式不工作 → 验证`darkMode: ["class"]`及ThemeProvider配置
- 类被清除 → 添加到安全列表或使用完整类名

Best Practices

最佳实践

  1. Mobile-first - Default styles for mobile, add breakpoints up
  2. CSS Variables - Use for theming (enables dark mode)
  3. Content paths - Include all component paths
  4. Semantic names - Use 
    brand
    , 
    accent
    not 
    blue-500
  5. Size utility - Use 
    size-*
    for equal dimensions
  1. 移动优先 - 默认样式适配移动端，向上添加断点样式
  2. CSS 变量 - 用于主题配置（支持暗色模式）
  3. 内容路径 - 包含所有组件路径
  4. 语义化命名 - 使用
    brand
    、
    accent
    而非
    blue-500
  5. 尺寸工具类 - 对等宽高元素使用
    size-*

References

参考资料