tailwind-4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Styling Decision Tree

样式决策树

Tailwind class exists?  → className="..."
Dynamic value?          → style={{ width: `${x}%` }}
Conditional styles?     → cn("base", condition && "variant")
Static only?            → className="..." (no cn() needed)
Library can't use class?→ style prop with var() constants

Tailwind class exists?  → className="..."
Dynamic value?          → style={{ width: `${x}%` }}
Conditional styles?     → cn("base", condition && "variant")
Static only?            → className="..." (no cn() needed)
Library can't use class?→ style prop with var() constants

Critical Rules

核心规则

Never Use var() in className

切勿在className中使用var()

typescript

// ❌ NEVER: var() in className
<div className="bg-[var(--color-primary)]" />
<div className="text-[var(--text-color)]" />

// ✅ ALWAYS: Use Tailwind semantic classes
<div className="bg-primary" />
<div className="text-slate-400" />

typescript

// ❌ 禁止：在className中使用var()
<div className="bg-[var(--color-primary)]" />
<div className="text-[var(--text-color)]" />

// ✅ 推荐：使用Tailwind语义化类名
<div className="bg-primary" />
<div className="text-slate-400" />

Never Use Hex Colors

切勿使用十六进制颜色

typescript

// ❌ NEVER: Hex colors in className
<p className="text-[#ffffff]" />
<div className="bg-[#1e293b]" />

// ✅ ALWAYS: Use Tailwind color classes
<p className="text-white" />
<div className="bg-slate-800" />

typescript

// ❌ 禁止：在className中使用十六进制颜色
<p className="text-[#ffffff]" />
<div className="bg-[#1e293b]" />

// ✅ 推荐：使用Tailwind颜色类名
<p className="text-white" />
<div className="bg-slate-800" />

The cn() Utility

cn() 工具函数

typescript

import { clsx } from "clsx";
import { twMerge } from "tailwind-merge";

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

typescript

import { clsx } from "clsx";
import { twMerge } from "tailwind-merge";

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

When to Use cn()

何时使用cn()

typescript

// ✅ Conditional classes
<div className={cn("base-class", isActive && "active-class")} />

// ✅ Merging with potential conflicts
<button className={cn("px-4 py-2", className)} />  // className might override

// ✅ Multiple conditions
<div className={cn(
  "rounded-lg border",
  variant === "primary" && "bg-blue-500 text-white",
  variant === "secondary" && "bg-gray-200 text-gray-800",
  disabled && "opacity-50 cursor-not-allowed"
)} />

typescript

// ✅ 条件类名
<div className={cn("base-class", isActive && "active-class")} />

// ✅ 合并可能存在冲突的类名
<button className={cn("px-4 py-2", className)} />  // className可能会覆盖原有类名

// ✅ 多条件场景
<div className={cn(
  "rounded-lg border",
  variant === "primary" && "bg-blue-500 text-white",
  variant === "secondary" && "bg-gray-200 text-gray-800",
  disabled && "opacity-50 cursor-not-allowed"
)} />

When NOT to Use cn()

何时不使用cn()

typescript

// ❌ Static classes - unnecessary wrapper
<div className={cn("flex items-center gap-2")} />

// ✅ Just use className directly
<div className="flex items-center gap-2" />

typescript

// ❌ 静态类名 - 无需额外包装
<div className={cn("flex items-center gap-2")} />

// ✅ 直接使用className
<div className="flex items-center gap-2" />

Style Constants for Charts/Libraries

图表/类库的样式常量

When libraries don't accept className (like Recharts):

typescript

// ✅ Constants with var() - ONLY for library props
const CHART_COLORS = {
  primary: "var(--color-primary)",
  secondary: "var(--color-secondary)",
  text: "var(--color-text)",
  gridLine: "var(--color-border)",
};

// Usage with Recharts (can't use className)
<XAxis tick={{ fill: CHART_COLORS.text }} />
<CartesianGrid stroke={CHART_COLORS.gridLine} />

当类库不支持className时（如Recharts）：

typescript

// ✅ 使用var()定义常量 - 仅用于类库属性
const CHART_COLORS = {
  primary: "var(--color-primary)",
  secondary: "var(--color-secondary)",
  text: "var(--color-text)",
  gridLine: "var(--color-border)",
};

// 在Recharts中使用（无法使用className）
<XAxis tick={{ fill: CHART_COLORS.text }} />
<CartesianGrid stroke={CHART_COLORS.gridLine} />

Dynamic Values

动态值处理

typescript

// ✅ style prop for truly dynamic values
<div style={{ width: `${percentage}%` }} />
<div style={{ opacity: isVisible ? 1 : 0 }} />

// ✅ CSS custom properties for theming
<div style={{ "--progress": `${value}%` } as React.CSSProperties} />

typescript

// ✅ 使用style属性处理真正的动态值
<div style={{ width: `${percentage}%` }} />
<div style={{ opacity: isVisible ? 1 : 0 }} />

// ✅ 使用CSS自定义属性实现主题化
<div style={{ "--progress": `${value}%` } as React.CSSProperties} />

Common Patterns

常见模式

Flexbox

Flexbox布局

typescript

<div className="flex items-center justify-between gap-4" />
<div className="flex flex-col gap-2" />
<div className="inline-flex items-center" />

typescript

<div className="flex items-center justify-between gap-4" />
<div className="flex flex-col gap-2" />
<div className="inline-flex items-center" />

Grid

Grid布局

typescript

<div className="grid grid-cols-3 gap-4" />
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6" />

typescript

<div className="grid grid-cols-3 gap-4" />
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6" />

Spacing

间距设置

typescript

// Padding
<div className="p-4" />           // All sides
<div className="px-4 py-2" />     // Horizontal, vertical
<div className="pt-4 pb-2" />     // Top, bottom

// Margin
<div className="m-4" />
<div className="mx-auto" />       // Center horizontally
<div className="mt-8 mb-4" />

typescript

// 内边距
<div className="p-4" />           // 四边
<div className="px-4 py-2" />     // 水平、垂直
<div className="pt-4 pb-2" />     // 顶部、底部

// 外边距
<div className="m-4" />
<div className="mx-auto" />       // 水平居中
<div className="mt-8 mb-4" />

Typography

排版

typescript

<h1 className="text-2xl font-bold text-white" />
<p className="text-sm text-slate-400" />
<span className="text-xs font-medium uppercase tracking-wide" />

typescript

<h1 className="text-2xl font-bold text-white" />
<p className="text-sm text-slate-400" />
<span className="text-xs font-medium uppercase tracking-wide" />

Borders & Shadows

边框与阴影

typescript

<div className="rounded-lg border border-slate-700" />
<div className="rounded-full shadow-lg" />
<div className="ring-2 ring-blue-500 ring-offset-2" />

typescript

<div className="rounded-lg border border-slate-700" />
<div className="rounded-full shadow-lg" />
<div className="ring-2 ring-blue-500 ring-offset-2" />

States

状态样式

typescript

<button className="hover:bg-blue-600 focus:ring-2 active:scale-95" />
<input className="focus:border-blue-500 focus:outline-none" />
<div className="group-hover:opacity-100" />

typescript

<button className="hover:bg-blue-600 focus:ring-2 active:scale-95" />
<input className="focus:border-blue-500 focus:outline-none" />
<div className="group-hover:opacity-100" />

Responsive

响应式设计

typescript

<div className="w-full md:w-1/2 lg:w-1/3" />
<div className="hidden md:block" />
<div className="text-sm md:text-base lg:text-lg" />

typescript

<div className="w-full md:w-1/2 lg:w-1/3" />
<div className="hidden md:block" />
<div className="text-sm md:text-base lg:text-lg" />

Dark Mode

暗黑模式

typescript

<div className="bg-white dark:bg-slate-900" />
<p className="text-gray-900 dark:text-white" />

typescript

<div className="bg-white dark:bg-slate-900" />
<p className="text-gray-900 dark:text-white" />

Arbitrary Values (Escape Hatch)

任意值（应急方案）

typescript

// ✅ OK for one-off values not in design system
<div className="w-[327px]" />
<div className="top-[117px]" />
<div className="grid-cols-[1fr_2fr_1fr]" />

// ❌ Don't use for colors - use theme instead
<div className="bg-[#1e293b]" />  // NO

typescript

// ✅ 适合设计系统中没有的一次性值
<div className="w-[327px]" />
<div className="top-[117px]" />
<div className="grid-cols-[1fr_2fr_1fr]" />

// ❌ 颜色请勿使用此方式 - 改用主题色
<div className="bg-[#1e293b]" />  // 不推荐

Keywords

关键词

tailwind, css, styling, cn, utility classes, responsive