tailwindcss

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS Developer Guide

Tailwind CSS 开发者指南

This skill provides guidelines, patterns, and best practices for working with Tailwind CSS v4 in this project.

本技能提供了在本项目中使用 Tailwind CSS v4 的规范、模式和最佳实践。

Quick Reference

快速参考

For detailed patterns, examples, and checklists, see:

references/patterns.md - Complete usage patterns, design tokens, and anti-patterns

如需了解详细的模式、示例和检查清单，请查看：

references/patterns.md - 完整的使用模式、Design Tokens 和反模式

Core Principles

核心原则

Utility-First: Embrace utility-first approach and avoid custom CSS.
Design Tokens: Always use design system tokens (
```
bg-background
```
,
```
text-foreground
```
) instead of explicit colors (
```
bg-white
```
,
```
text-black
```
).
Tailwind Variants: Use
```
tailwind-variants
```
(tv) for component styling instead of CVA.
Mobile-First: Build responsive layouts with mobile-first approach.

Utility-First：遵循实用优先的开发方式，避免编写自定义 CSS。
Design Tokens：始终使用设计系统令牌（
```
bg-background
```
、
```
text-foreground
```
）而非硬编码颜色（
```
bg-white
```
、
```
text-black
```
）。
Tailwind Variants：使用
```
tailwind-variants
```
（tv）实现组件样式，不使用 CVA。
Mobile-First：采用移动端优先的方式构建响应式布局。

Critical: Design Token Usage

重要提示：Design Token 使用规范

To ensure theme switching works correctly:

Always use:

Backgrounds:
```
bg-background
```
,
```
bg-card
```
,
```
bg-muted
```
,
```
bg-popover
```

Text:

text-foreground

text-muted-foreground

text-card-foreground

Borders:
```
border-border
```
,
```
border-input
```
,
```
border-ring
```

Actions:

bg-primary text-primary-foreground

bg-secondary text-secondary-foreground

States:

bg-destructive text-destructive-foreground

bg-accent text-accent-foreground

Never use:

bg-white

text-black

border-gray-200

bg-blue-500

为确保主题切换功能正常运行：

请始终使用：

背景类：
```
bg-background
```
、
```
bg-card
```
、
```
bg-muted
```
、
```
bg-popover
```

文本类：

text-foreground

、

text-muted-foreground

、

text-card-foreground

边框类：
```
border-border
```
、
```
border-input
```
、
```
border-ring
```

操作类：

bg-primary text-primary-foreground

、

bg-secondary text-secondary-foreground

状态类：

bg-destructive text-destructive-foreground

、

bg-accent text-accent-foreground

禁止使用：

bg-white

、

text-black

、

border-gray-200

、

bg-blue-500

Common Tasks

常见任务

Component Styling with Tailwind Variants

使用 Tailwind Variants 实现组件样式

typescript

import { tv } from 'tailwind-variants'

const button = tv({
  base: [
    'inline-flex items-center justify-center rounded-md',
    'text-sm font-medium transition-colors',
    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
  ],
  variants: {
    variant: {
      default: 'bg-primary text-primary-foreground hover:bg-primary/90',
      outline: 'border border-input hover:bg-accent hover:text-accent-foreground',
    },
    size: {
      default: 'h-10 py-2 px-4',
      sm: 'h-9 px-3 rounded-md',
      icon: 'size-10',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
})

typescript

import { tv } from 'tailwind-variants'

const button = tv({
  base: [
    'inline-flex items-center justify-center rounded-md',
    'text-sm font-medium transition-colors',
    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
  ],
  variants: {
    variant: {
      default: 'bg-primary text-primary-foreground hover:bg-primary/90',
      outline: 'border border-input hover:bg-accent hover:text-accent-foreground',
    },
    size: {
      default: 'h-10 py-2 px-4',
      sm: 'h-9 px-3 rounded-md',
      icon: 'size-10',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
})

Long Class Strings

长类名字符串处理

Break class strings longer than 100 characters into arrays:

typescript

// Good: Break into logical arrays
const card = tv({
  base: [
    'relative flex flex-col rounded-xl border border-border',
    'bg-card text-card-foreground shadow-xs transition-colors duration-150',
  ],
})

长度超过100字符的类名字符串请拆分为数组：

typescript

// Good: Break into logical arrays
const card = tv({
  base: [
    'relative flex flex-col rounded-xl border border-border',
    'bg-card text-card-foreground shadow-xs transition-colors duration-150',
  ],
})

Responsive Design

响应式设计

tsx

// Mobile-first responsive design
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">

// Container queries (built-in in v4)
<div className="@container">
  <div className="@lg:flex @lg:items-center">

tsx

// Mobile-first responsive design
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">

// Container queries (built-in in v4)
<div className="@container">
  <div className="@lg:flex @lg:items-center">

Modern v4 Utilities

v4 新增实用工具

tsx

<div className="size-10">          {/* Instead of w-10 h-10 */}
<div className="h-dvh">            {/* Dynamic viewport height */}
<div className="grid-cols-15">     {/* Dynamic grid columns */}
<h1 className="text-shadow-md">    {/* Text shadows */}
<div className="bg-(--custom-color)">  {/* CSS variables */}

tsx

<div className="size-10">          {/* Instead of w-10 h-10 */}
<div className="h-dvh">            {/* Dynamic viewport height */}
<div className="grid-cols-15">     {/* Dynamic grid columns */}
<h1 className="text-shadow-md">    {/* Text shadows */}
<div className="bg-(--custom-color)">  {/* CSS variables */}

Anti-Patterns to Avoid

需要避免的反模式

Don't use
```
@apply
```
except for base styles
Avoid inline styles when Tailwind has utilities
Don't create utility classes that duplicate Tailwind
Never use
```
!important
```
unless absolutely necessary
Don't construct classes dynamically (
```
bg-${color}-500
```
)

除非是基础样式，否则不要使用
```
@apply
```
当 Tailwind 有对应实用工具时，避免使用内联样式
不要创建与 Tailwind 内置功能重复的实用类
除非万不得已，不要使用
```
!important
```
不要动态拼接类名（
```
bg-${color}-500
```
）

Validation Checklist

验证检查清单

Before finishing a task involving Tailwind CSS:

Using design tokens instead of explicit colors
Long class strings broken into arrays (>100 chars)
Using
```
tailwind-variants
```
for component styling
Mobile-first responsive approach
Run lint checks (
```
pnpm run lint
```
)

For detailed rules, anti-patterns, and configuration examples, see references/patterns.md.

完成涉及 Tailwind CSS 的开发任务前，请确认：

已使用 Design Tokens 而非硬编码颜色
长度超过100字符的类名字符串已拆分为数组
已使用
```
tailwind-variants
```
实现组件样式
采用了移动端优先的响应式开发方式
已执行 lint 检查（
```
pnpm run lint
```
）

如需了解详细规则、反模式和配置示例，请查看 references/patterns.md。