frontend-tailwind-best-practices

Tailwind CSS のベストプラクティス

フロントエンドアプリケーションのスタイリングパターンと規約です。レイアウトユーティリティ、アフォーダンス、カラースキーム、レスポンシブデザイン、className の扱いに関する 10 個のルールをまとめています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 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 - 重ね合わせるスタック（グリッドベースで、子要素を互いに重ねて中央に配置）
• 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

コンポーネント内で className を結合するときは、必ず cn() を使用します。

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]	デザイントークンを使用
className="..." without cn()	cn("...", className)
レスポンシブ対応にインラインの style	Tailwind のプレフィックス

主要ファイル

ファイル	用途
tailwind.config.js	設定、カスタムユーティリティ、カラー
app/styles/global.css	カラースキームの CSS 変数
app/styles/tailwind.css	追加のユーティリティ
app/utils/cn.ts	className 結合ユーティリティ