tailwindcss-best-practices

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

ドキュメントのスナップショット：Tailwind CSS v4.3.3。2026-08-29 に npm の latest タグおよび公式ドキュメントと照合済みです。ユーザーが最新バージョンを尋ねた場合は、https://tailwindcss.com/docs と npm のタグを再確認してください。

Tailwind v4 は CSS ファーストです。@theme でデザイントークンを定義し、@utility でユーティリティを登録し、@custom-variant でバリアントを登録します。従来の JavaScript 設定は引き続き @config で利用できますが、自動検出されず、一部の v3 オプションはサポートされていません。

作業方法

1. 編集する前にプロジェクトを調査します。 インストール済みの tailwindcss のバージョン、パッケージマネージャー、ビルド統合、メイン CSS エントリーポイント、従来の設定やプラグイン、ソースルート、既存のデザイントークンやコンポーネントを特定します。このスキルで説明しているバージョンが新しいという理由だけで、プロジェクトをアップグレードしないでください。
2. スタックに合った統合方法を選びます。 公式ガイドがある場合は、フレームワークの公式ガイドを優先してください。Vite ベースのスタックには @tailwindcss/vite、Next.js など PostCSS ベースのスタックには @tailwindcss/postcss、webpack ローダーとしては @tailwindcss/webpack、スタンドアロンのビルドには @tailwindcss/cli を使用します。ビルド設定を変更する前に、インストールを読んでください。
3. 要件に合う最小限のスタイル指定方法を使います。 既存のユーティリティやコンポーネントを優先し、真に一度限りの用途には任意の値を使い、デザイン値を再利用する場合は @theme トークンを追加し、再利用可能な CSS 機能に限って @utility を追加します。サードパーティーの上書きや、CSS として記述するほうが明快なルールにはカスタム CSS を使います。
4. 候補が静的に検出できる状態を保ちます。 プロパティや状態を、完成したクラス文字列に対応付けます。`bg-${color}-500` のような断片を組み立てないでください。モノレポ、外部パッケージ、除外、セーフリストについては、ソースの検出を読んでください。
5. 既存のデザインシステムを維持します。 既存のスペーシング、色、タイポグラフィ、角丸、コンポーネント、クラス結合の規約を再利用してください。対応するトークンがすでにある場合は、任意の値を新たに導入しないでください。
6. 実際の表示結果を検証します。 関連するビルド、型チェック、Lint、テストを実行し、検出に疑問がある場合は、期待するユーティリティがコンパイル済み CSS に含まれていることを確認します。該当する場合は、レンダリングされた UI でレスポンシブ、状態、ダークモード、フォーカス、動きの軽減時の動作も確認します。

v4.3 の追加機能

機能	用途
スクロールバー	scrollbar-auto、scrollbar-thin、scrollbar-none、scrollbar-thumb-*、scrollbar-track-*、scrollbar-gutter-*。スクロールバーを参照してください
サイズコンテナー	クエリやコンテナ単位でブロックサイズの情報が必要な場合は、@container-size または @container-size/{name} を使用します。レスポンシブデザインを参照してください
ズーム	CSS の zoom には、zoom-*、zoom-[value]、zoom-(--property) を使用します。トランスフォームを参照してください
タブサイズ	表示されるタブ幅には、tab-*、tab-[value]、tab-(--property) を使用します。タイポグラフィを参照してください
CSS 内のバリアント	バリアントを重ねるには @variant hover:focus を、共有ブロックには @variant hover, focus を使用します
関数型ユーティリティ	単独のユーティリティにフォールバックが必要な場合は、--value(...) または --modifier(...) 内で --default(...) を使用します。関数とディレクティブを参照してください

v4 への移行で特に注意すべき点

Tailwind v4 を使用する際によくある間違いをまとめました。v3 から移行する場合や、初めて v4 を使用する場合は、アップグレードガイドをお読みください。特に注意すべき点は次のとおりです。

v3（旧）	v4（正）	変更理由
!bg-red-500	bg-red-500!	!important 修飾子が接頭辞から接尾辞に移動しました
bg-opacity-75	bg-red-500/75	不透明度修飾子が削除されました。色にスラッシュ構文を使用します
shadow	shadow-sm	シャドウのスケールが1段階小さくなりました
shadow-sm	shadow-xs	シャドウのスケールが1段階小さくなりました
rounded	rounded-sm	角丸のスケールが1段階小さくなりました
rounded-sm	rounded-xs	角丸のスケールが1段階小さくなりました
ring	ring-3	デフォルトのリング幅が3pxから1pxに変更されました
outline-none	outline-hidden	より明確になるよう名称が変更されました
flex-shrink-0	shrink-0	短いエイリアスのみが使用できるようになりました
flex-grow	grow	短いエイリアスのみが使用できるようになりました
overflow-ellipsis	text-ellipsis	一貫性を保つため名称が変更されました
blur	blur-sm	ぼかしのスケールが1段階小さくなりました
@tailwind base/components/utilities	@import "tailwindcss"	3つのディレクティブが1つの CSS インポートに置き換わりました
自動検出される tailwind.config.js	CSS ファーストのディレクティブ、または互換性のための明示的な @config	JS 設定が自動検出されなくなりました
darkMode: 'class'	@custom-variant dark (&:where(.dark, .dark *));	ダークモードの設定が CSS に移動しました
bg-[--var]	bg-(--var)	CSS 変数の任意値では丸括弧を使用します
theme(screens.xl)	theme(--breakpoint-xl)	theme 関数で CSS 変数名を使用します
@layer utilities { }	@utility name { }	カスタムユーティリティには専用のディレクティブを使用します
start-* / end-*	inset-s-* / inset-e-*	v4.2 で非推奨になりました

コアリファレンス

トピック	説明	リファレンス
インストール	Vite、PostCSS、Webpack、CLI、CDN のセットアップ	core-installation
ユーティリティクラス	Tailwind のユーティリティファーストのアプローチについて	core-utility-classes
テーマ変数	デザイントークン、@theme ディレクティブ、テーマ変数の名前空間	core-theme
レスポンシブデザイン	モバイルファーストのブレークポイント、レスポンシブバリアント、コンテナクエリ	core-responsive
バリアント	状態、疑似クラス、メディアクエリ、ポインターバリアントによる条件付きスタイル設定	core-variants
Preflight	Tailwind のベーススタイルとその拡張または無効化の方法	core-preflight
ソース検出	Tailwind によるクラスの検出方法、@source、@source not、@source inline()	core-source-detection

レイアウト

Display、Flexbox、Grid

トピック	説明	リファレンス
Display	flex、grid、block、inline、hidden、sr-only、flow-root、contents	layout-display
Flexbox	flex-direction、justify、items、gap、grow、shrink、wrap、order	layout-flexbox
Grid	grid-cols、grid-rows、gap、place-items、col-span、row-span、subgrid	layout-grid
アスペクト比	レスポンシブメディア向けの要素のアスペクト比の調整	layout-aspect-ratio
Columns	雑誌風またはメイソンリーレイアウト向けのマルチカラムレイアウト	layout-columns

配置

トピック	説明	リファレンス
配置	static、relative、absolute、fixed、sticky を使った要素の配置制御	layout-position
インセット	inset、論理インセット（inset-s-*、inset-bs-*）、非推奨の start-*／end-* を使った配置済み要素の位置指定	layout-inset

サイズ設定

トピック	説明	リファレンス
幅	スペーシングスケール、分数、コンテナーサイズ、ビューポート単位を使った要素幅の設定	layout-width
高さ	スペーシングスケール、分数、ビューポート単位を使った要素の高さの設定	layout-height
最小・最大サイズ	min-width、max-width、min-height、max-height による制約	layout-min-max-sizing
論理サイズ	書字方向を考慮したサイズ設定：inline-*、block-*、min-inline-*、max-block-*（v4.2）	layout-logical-properties

余白

トピック	説明	リファレンス
マージン	スペーシングスケール、負の値、論理プロパティ（mbs-*、mbe-*）によるマージン	layout-margin
パディング	スペーシングスケール、論理プロパティ（pbs-*、pbe-*）によるパディング	layout-padding

オーバーフロー

トピック	説明	リファレンス
オーバーフロー	コンテンツがはみ出した場合の要素の動作を制御	layout-overflow

画像と置換要素

トピック	説明	リファレンス
オブジェクトのフィットと位置	画像や動画のサイズ変更と配置を制御	layout-object-fit-position

テーブル

トピック	説明	リファレンス
テーブルレイアウト	border-collapse、table-auto、table-fixed	layout-tables

変形

トピック	説明	リファレンス
変形の基本	変形ユーティリティの基本、ハードウェアアクセラレーション、カスタム変形値	transform-base
移動	スペーシングスケールとパーセンテージを使った、x、y、z 軸方向への要素の移動	transform-translate
回転	2D および 3D 空間での要素の回転	transform-rotate
拡大縮小	要素全体または特定の軸に沿った拡大縮小	transform-scale
傾斜	x 軸および y 軸に沿った要素の傾斜	transform-skew

タイポグラフィ

トピック	説明	リファレンス
フォントとテキスト	フォントサイズ、太さ、色、行の高さ、文字間隔、装飾、省略表示、wrap-break-word、wrap-anywhere	typography-font-text
テキスト揃え	左揃え、中央揃え、右揃え、両端揃えによるテキストの配置制御	typography-text-align
リストスタイル	箇条書きとマーカーの list-style-type、list-style-position	typography-list-style

ビジュアル

トピック	説明	参考資料
背景	背景色、グラデーション、画像、サイズ、位置	visual-background
ボーダー	ボーダーの幅、色、角丸、区切り線、リング、ブロックボーダー用ユーティリティ（border-bs-*、border-be-*）	visual-border
エフェクト	ボックスシャドウ、不透明度、mix-blend、backdrop-blur、フィルター、色付きドロップシャドウ	visual-effects
SVG	SVG およびアイコンのスタイリングに使う fill、stroke、stroke-width	visual-svg
テキストシャドウ	テキストシャドウのサイズ、色、不透明度の修飾子（v4.1）	effects-text-shadow
マスク	グラデーションマスクと放射状マスクを組み合わせて使えるユーティリティ（v4.1）	effects-mask
スクロールバー	幅、つまみ／トラックの色、安定したガター用ユーティリティ（v4.3）	effects-scrollbars

エフェクトとインタラクティブ機能

トピック	説明	参考資料
トランジションとアニメーション	CSS トランジション、アニメーションのキーフレーム、動きを抑制する設定	effects-transition-animation
可視性とインタラクティブ機能	可視性、カーソル、pointer-events、user-select、z-index	effects-visibility-interactivity
フォームコントロール	accent-color、appearance、caret-color、resize	effects-form-controls
スクロールスナップ	カルーセル向けの scroll-snap-type、scroll-snap-align	effects-scroll-snap

機能

ダークモード

トピック	説明	参考資料
ダークモード	dark: バリアント、@custom-variant、クラスとデータ属性による方式を使ったダークモード	features-dark-mode

移行

トピック	説明	参考資料
アップグレードガイド	v3 から v4 への移行、名前変更・削除されたすべてのユーティリティ、スケールの変更、設定の移行	features-upgrade

カスタマイズ

トピック	説明	参考資料
カスタムスタイル	カスタムスタイル、@utility によるユーティリティ、@custom-variant によるバリアント、任意の値の追加	features-custom-styles
関数とディレクティブ	Tailwind の CSS ディレクティブ（@theme、@utility、@custom-variant、@source）と関数	features-functions-directives
コンテンツの検出	Tailwind がクラスを検出する仕組み、@source の設定、@source inline() によるセーフリスト登録	features-content-detection

ベストプラクティス

トピック	説明	参考資料
ユーティリティのパターン	重複や競合、important 修飾子の管理、コンポーネントを使うタイミング	best-practices-utility-patterns

主な推奨事項

• 新たな抽象化レイヤーを追加するより、ユーティリティと既存のコンポーネントを優先してください。
• 再利用可能なデザイントークンは @theme で定義し、ユーティリティを生成すべきでない CSS 変数には :root を使ってください。
• プレフィックスのないレスポンシブユーティリティをモバイル向けの基本設定として扱い、ブレークポイントのバリアントで上書きしてください。
• ソースには候補文字列を完全な形で記述し、動的な入力は静的なクラスリストに対応付けてください。
• @custom-variant でバリアントを定義し、CSS 内で既存のバリアントを適用するには @variant を使ってください。
• v4 の新規開発では CSS ファーストの設定を優先し、互換性のために必要な場合に限り @config または @plugin を残してください。
• ブレークポイントには単位を統一して使ってください。公式のデフォルトでは rem が使われており、単位が混在すると予期しない順序になることがあります。
• 本番環境で Play CDN を使ったり、Tailwind v4 の前段に Sass／Less／Stylus を追加したりしないでください。