frontend-tailwind-best-practices

用途

这是一套面向前端应用的 Tailwind CSS 样式模式与约定集合，共包含 10 条规则，覆盖布局工具类、视觉可供性（affordances）、配色方案、响应式设计以及 className 处理。当你在使用 Tailwind 编写组件样式、创建布局（堆叠、网格、居中）、处理响应式设计、使用配色方案或合并 className 属性时，可参考这些指南。

主要能力

布局工具类（CRITICAL）

layout-stack-utilities：使用自定义 stack 工具类替代 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 - 使用 aspect-ratio 1/1 的完美圆形

layout-prefer-gaps：在父元素上使用 gap-* 而非子元素 margin。

// 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：在断点处切换布局方向。

// 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">

配色方案（CRITICAL）

color-schemes：使用基于 class 的配色方案，配合自定义 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 处理（CRITICAL）

classname-cn-utility：在组件中始终使用 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：为 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" }} />;

视觉可供性（HIGH）

affordance-classes：定义与元素无关、可与工具类组合的视觉模式。

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

响应式设计（MEDIUM）

responsive-breakpoints：使用响应式前缀配合 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：响应式缩放文本。

// 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：针对输入能力（pointer/hover）设计，而非设备标签。

<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]	使用设计令牌
className="..." 未使用 cn()	cn("...", className)
响应式使用内联样式	Tailwind 前缀

关键文件

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

适用场景

适用于使用 Tailwind CSS 的前端项目，尤其是需要统一组件样式约定、规范布局写法、处理响应式与配色、以及合并 className 属性的团队协作场景。

限制

资料未提供该技能的具体安装方式、运行环境要求、版本兼容性、收费信息及实际效果说明，这些内容暂未提供。