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 - 完整的使用模式、设计令牌与反模式

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
```
).
Mobile-First: Build responsive layouts with mobile-first approach.

优先使用实用类：采用实用类优先的方法，避免自定义CSS。
设计令牌：始终使用设计系统令牌（如
```
bg-background
```
、
```
text-foreground
```
），而非明确的颜色值（如
```
bg-white
```
、
```
text-black
```
）。
移动优先：采用移动优先的方法构建响应式布局。

Critical: Design Token Usage

重点：设计令牌的使用

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

常见任务

Long Class Strings

长类名字符串

Break class strings longer than 100 characters into arrays:

typescript

const cardBaseClasses = [
  "relative flex flex-col rounded-xl border border-border",
  "bg-card text-card-foreground shadow-xs transition-colors duration-150",
];

// Usage: className={cardBaseClasses.join(' ')} or spread into cn()/clsx

将超过100个字符的类名字符串拆分为数组：

typescript

const cardBaseClasses = [
  "relative flex flex-col rounded-xl border border-border",
  "bg-card text-card-foreground shadow-xs transition-colors duration-150",
];

// 使用方式：className={cardBaseClasses.join(' ')} 或展开到 cn()/clsx 中

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

// 移动优先的响应式设计
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">

// 容器查询（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">          {/* 替代 w-10 h-10 */}
<div className="h-dvh">            {/* 动态视口高度 */}
<div className="grid-cols-15">     {/* 动态网格列数 */}
<h1 className="text-shadow-md">    {/* 文本阴影 */}
<div className="bg-(--custom-color)">  {/* CSS 变量 */}

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)
Mobile-first responsive approach
Run lint checks (
```
pnpm run lint
```
)

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

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

使用设计令牌而非明确的颜色值
超过100字符的长类名字符串已拆分为数组
采用移动优先的响应式设计方法
运行lint检查（
```
pnpm run lint
```
）

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