frontend-tailwind-best-practices

Tailwind CSS 最佳实践

用于前端应用的样式模式和约定。包含 10 条规则，涵盖布局工具类、可操作性、配色方案、响应式设计和 className 处理。

适用场景

在以下情况下参考这些指南：

• 使用 Tailwind 编写组件样式
• 创建布局（堆叠、网格、居中）
• 处理响应式设计
• 使用配色方案
• 合并 className 属性

规则摘要

布局工具类（关键）

layout-stack-utilities - @rules/layout-stack-utilities.md

使用自定义堆叠工具类，而不是 flex 类。

// Bad
<div className="flex flex-col gap-4">
<div className="flex flex-row gap-4">

// Good
<div className="v-stack gap-4">
<div className="h-stack gap-4">

可用工具类：

• v-stack - 垂直堆叠（flex column）
• h-stack - 水平堆叠（flex row）
• v-stack-reverse - 反向垂直堆叠
• h-stack-reverse - 反向水平堆叠
• z-stack - 重叠堆叠（基于 grid，让子元素彼此叠放并居中）
• center - 水平和垂直居中内容
• spacer - 填充可用空间的弹性间隔元素
• circle - 宽高比为 1/1 的正圆

layout-prefer-gaps - @rules/layout-prefer-gaps.md

在父元素上使用 gap-*，而不是对子元素设置外边距。

// Bad
<div>
  <Item className="mb-4" />
  <Item className="mb-4" />
</div>

// Good
<div className="flex flex-col gap-4">
  <Item />
  <Item />
</div>

layout-responsive-stacks - @rules/layout-responsive-stacks.md

在断点处切换布局方向。

// Mobile: vertical, Desktop: horizontal
<div className="v-stack lg:h-stack gap-4">
  <main className="grow">...</main>
  <aside className="shrink-0 lg:w-80">...</aside>
</div>

// Mobile: horizontal, Desktop: vertical
<div className="h-stack md:v-stack">

配色方案（关键）

color-schemes - @rules/color-schemes.md

使用基于类的配色方案，并配合自定义 dark 变体。

<button className="rounded-full bg-gray-900 px-4 py-2 text-white dark:bg-gray-100 dark:text-gray-900">
  Toggle
</button>

className 处理（关键）

classname-cn-utility - @rules/classname-cn-utility.md

始终使用 cn() 合并组件中的 className。

import { cn } from "~/lib/cn";

function Button({ className, variant }: Props) {
  return (
    <button
      className={cn(
        "base-classes",
        {
          "variant-primary": variant === "primary",
          "variant-secondary": variant === "secondary",
        },
        className, // external className always last
      )}
    />
  );
}

classname-prop-types - @rules/classname-prop-types.md

为 className 属性使用合适的类型。

import type { ClassName, ClassNameRecord } from "~/lib/cn";

// Single element
type Props = {
  className?: ClassName;
};

// Multiple elements
type Props = {
  className?: ClassNameRecord<"root" | "label" | "input">;
};

// Usage
<Input className={{ root: "w-full", label: "font-bold" }} />;

可操作性（高）

affordance-classes - @rules/affordance-classes.md

定义与元素无关、可与工具类组合使用的视觉模式。

<label className="ui-button" htmlFor="document-upload">
  Choose file
</label>

响应式设计（中）

responsive-breakpoints - @rules/responsive-breakpoints.md

使用 Tailwind 默认的响应式前缀。

// Standard breakpoints (min-width)
<div className="px-4 md:px-8 lg:px-12">

// Show/hide with standard breakpoints
<div className="hidden md:block">Desktop only</div>
<div className="md:hidden">Mobile only</div>

responsive-text - @rules/responsive-text.md

让文本大小随屏幕尺寸自适应。

// Responsive font size
<h1 className="text-2xl md:text-3xl lg:text-4xl">

// Responsive line height with text
<p className="text-sm leading-5 md:text-base md:leading-6">

responsive-capabilities - @rules/responsive-capabilities.md

根据输入能力（指针／悬停）而不是设备标签进行设计。

<button className="h-10 w-10 pointer-coarse:h-12 pointer-coarse:w-12">
  <Icon />
</button>

反模式

不要这样做	应这样做
flex flex-col	v-stack
flex flex-row	h-stack
flex items-center justify-center	center
bg-gray-100	bg-neutral-100
bg-[#hex]	使用设计令牌
不使用 cn() 的 className="..."	cn("...", className)
使用内联 style 实现响应式	使用 Tailwind 前缀

关键文件

文件	用途
tailwind.config.js	配置、自定义工具类、颜色
app/styles/global.css	配色方案 CSS 变量
app/styles/tailwind.css	其他工具类
app/utils/cn.ts	className 合并工具