tailwind-best-practices

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

このスキルは、Evil Martians が構築しました。同社は、開発者向けツール、AI、サイバーセキュリティのスタートアップを支援する、アメリカのデザインおよびエンジニアリングコンサルティング会社です。

以下のチェック項目を適用して、Tailwind CSS のコードベースが大きくなっても読みやすさを保ちましょう。https://evilmartians.com/chronicles/5-best-practices-for-preventing-chaos-in-tailwind-css の補足資料です。

Tailwind のユーティリティファーストのアプローチで保守性を保つには、次の 2 つの条件を満たす必要があります。ほかのことに着手する前に、両方を確認してください。

1. トークンを備えたデザインシステムがあること（色、余白、タイポグラフィのスケールが一元的に定義され、すべての場所で再利用されていること。ファイルごとにマジックナンバーを手入力して繰り返していないこと）。
2. コンポーネントベースのアプローチを採用していること。これにより、繰り返し使うクラスリストをコピー＆ペーストせずに、コンポーネントとして切り出せます。

どちらかの条件が満たされていないと確認できた場合は、その旨を伝えてそこで止めてください。基盤が欠けた状態で Tailwind の修正を提案しても、混乱が増すだけです。単に判断するためのコンテキストが不足している場合（たとえば、1 つのファイルしか見ていない場合）は、どちらかが欠けていると決めつける前に設定ファイルやテーマファイルを確認してください。ただし、それを理由に作業を止めず、前提を明示して作業を進めてください。

ワークフロー

各チェック項目は、それぞれ個別に実行できます。

1. 不要なユーティリティクラスを削減する

長いクラスリストをそのまま受け入れる前に、短縮できないか確認してください。

• pt-4 pb-4 → py-4（px、mx、my も同様です）
• flex flex-row justify-between → flex justify-between（flex-row は CSS のデフォルトです）
• border border-dotted border-2 border-black border-opacity-50 → border-dotted border-2 border-black/50

リスト内のクラスはすべて、後から読む人が把握しなければならない要素です。クラスが多く疎らなリストより、少なくて凝縮されたリストのほうがすばやく読めます。新しいクラスを書くときや、整理を明示的に依頼されたときに適用してください。別の作業中にたまたま通りかかった、無関係なクラスリストまで便乗して書き換えないでください。

2. デザイントークンを分類し、意味のある名前を付ける

トークンを無秩序に増やさないでください。カテゴリ（色、余白、ブレークポイントなど）ごとに分類し、元の値ではなく用途に基づいて名前を付けてください。たとえば、Figma からコピーした bright-red ではなく、error とします。

colors: { primary, secondary, error }
spacing: { sm, md, lg }
screens: { sm, md }

未使用のトークンも指摘してください。設定が乱雑になるだけでなく、デザインシステムで実際に使われているものを把握しようとする人を混乱させます。ただし、これは指摘にとどめ、自動的に削除しないでください。トークンが未使用だと結論づける前に、動的な使用箇所（例：`bg-${color}-500`、またはリポジトリ内の別の場所にある class-variance-authority や tailwind-variants の設定）を確認してください。リテラル名の単純な grep では、こうした使用箇所を見落とします。

3. クラスの並び順を統一し、自動化する

Tailwind のクラスリストを作成または編集するときは、常に自分で統一された順序にして出力し、並べ替えを後回しにしないでください。まず、公式の Tailwind CSS プラグインを使用する既存の Prettier 設定があるか確認し、チームのツールがすでに適用している順序に合わせてください。これにより、差分のノイズを防げます。そのような設定がない場合は、プラグインのデフォルトの順序に従います。ベースレイヤーのクラス、コンポーネントレイヤーのクラス、ユーティリティレイヤーのクラスの順に並べます。また、公式の Tailwind CSS 用 Prettier プラグインが導入されていない場合は、それを推奨してください。チーム全体でこのルールを自動的に適用できるようになります。

4. 繰り返し使うスタイルを切り出すために @apply を使わない

/* Avoid: */
.block {
  @apply bg-red-500 text-white p-4 rounded-lg hover:bg-blue-500;
}

これでは Tailwind の本来の利点が失われます。クラスに名前を付ける必要が生じ、スタイルの変更を使用しているコンポーネント内に閉じ込められなくなります。また、CSS バンドルのサイズも大きくなります。代わりに、実際のコンポーネントを使うよう提案してください（前提条件の #2 を参照）。すでにコードベースで @apply を多用している場合、一括書き換えは提案しないでください。技術的負債として指摘し、次に該当箇所へ手を入れるときに置き換えてください。

5. デザインシステムのコンポーネントで、props を通じて任意のクラスを受け入れないようにする

このルールはデザインシステムのコンポーネント（ボタン、バッジ、入力欄など、アプリ全体で一貫した見た目を保つことを目的としたものすべて）に適用されます。一度限りの単独使用コンポーネントであれば、className prop を自由に指定できても問題ありません。そうしたコンポーネントにまでバリアントを強制しないでください。どちらに当てはまるか判断しにくい場合は、そのコンポーネントが複数の場所でインポートされているか確認してください。

// Avoid, for a shared design-system component:
export const Button = ({ className = "bg-white" }) => (
  <button className={className}>Test</button>
);

共有コンポーネントを使うたびに呼び出し側が独自のユーティリティの組み合わせを作れるようにすると、時間の経過とともに視覚的な一貫性が損なわれます。代わりに、固定のバリアントマップを推奨してください。

const BUTTON_VARIANTS = {
  primary: "bg-blue-500 hover:bg-blue-600 text-white",
  secondary: "bg-gray-500 hover:bg-gray-600 text-white",
};

export const Button = ({ className, variant = BUTTON_VARIANTS.primary }) => (
  <button className={clsx(className, variant)}>Test</button>
);

チームが固定バリアントに抵抗する場合、実行時にクラスの競合を解決する代替策として tailwind-merge を使うのは問題ありません。ただし、バンドルサイズが増えるため、デフォルトの選択肢としては推奨しないでください。

アンチパターン：これらには異議を唱える

そのまま実装するのではなく、断るか、トレードオフを説明してください。

• クラスリスト内のマジック値（p-[123px]）。トークンシステムがある場合は、その値をトークン設定に追加するよう勧めてください。
• 場当たり的に追加される単発のトークン（15px、16px、17px）。既存のスケールを再利用または拡張する代わりに追加する場合は、フラグを立てて、それをトークンにすべきか確認してください。ただし、即座に拒否する必要はありません。外部アセットの正確な寸法に合わせる場合や、仕様を忠実に再現する場合など、単発の値が本当に適切なこともあります。
• 「よりすっきりする」として提案される、@apply に依存したスタイルシート。見た目の整理と引き換えに、Tailwind の本来のメリットを損ないます。
• 本番用 CSS の圧縮を省略すること。まず package.json またはロックファイルで Tailwind のバージョンを確認してください。v4 なら圧縮は自動的に行われます（Lightning CSS を基盤としているため）。変更は不要です。v3 なら、ビルドで圧縮のステップが実際に実行されているか確認してください。実行されていない場合は、ユーザーに追加を勧めてください（CLI の --minify フラグ、または PostCSS のプラグインリストに cssnano を追加します）。作業環境からバージョンを確認できない場合（例：リポジトリにアクセスできず、単一ファイルだけを編集している場合）は、どちらに当てはまるか推測して圧縮の話を持ち出すのではなく、何も指摘しないでください。

パターンはいつも同じです。小規模では問題なさそうに見える近道が、後になってコードベース全体で何度も検索と置換を行う作業につながります。最初からトークンまたはコンポーネントを使う方法を勧めてください。