tailwind-refactor

Tailwind CSS のリファクタリングに関するコミュニティのベストプラクティス

Tailwind CSS v4 を対象としたアプリケーション向けの、包括的なコード品質リファクタリングガイドです。移行の緊急度に応じて優先順位付けされた、8 カテゴリーにわたる 50 のルールを掲載しています。すべての変換で既存の見た目と操作感を維持します。このスキルは、コードの整理、最新の構文、v4 との互換性のみを対象としています。

関連スキル： デザインの改善には tailwind-ui-refactor を、レスポンシブなレイアウトパターンには tailwind-responsive-ui を使用してください。

適用するタイミング

手動で移行する前に： まず npx @tailwindcss/upgrade を実行してください。設定や名前が変更されたユーティリティの大半は、このツールで自動的に処理できます。その後、自動ツールでは対応できないパターンにこのスキルを使用してください。

以下の場合に、これらのガイドラインを参照してください。

• プロジェクトを Tailwind CSS v3 から v4 に移行する
• 非推奨または名前が変更されたユーティリティクラスを整理する
• 冗長な複数クラスのパターンを統合する
• 任意の値をデザイントークンに置き換える
• CSS ファイルでの @apply の過剰な使用を取り除く
• 構文を v4 の規約に合わせて最新化する

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	設定の移行	CRITICAL	config-
2	非推奨ユーティリティの置き換え	CRITICAL	dep-
3	名前が変更されたユーティリティの更新	HIGH	rename-
4	クラスの統合	HIGH	class-
5	任意の値の整理	MEDIUM-HIGH	arb-
6	構文の最新化	MEDIUM	syntax-
7	@apply とアーキテクチャの整理	MEDIUM	arch-
8	最新機能の採用	LOW-MEDIUM	adopt-

クイックリファレンス

1. 設定の移行（CRITICAL）

• config-import-directive - @tailwind ディレクティブを @import に置き換える
• config-css-theme - tailwind.config.js を CSS の @theme に移行する
• config-theme-function - theme() 関数を CSS 変数に置き換える
• config-theme-inline - ユーティリティ以外のデザイントークンに @theme inline を使用する
• config-utility-directive - @layer utilities を @utility に置き換える
• config-postcss-plugin - PostCSS プラグインを @tailwindcss/postcss に更新する
• config-content-autodetect - 手動のコンテンツ設定を削除する
• config-custom-variant - addVariant を @custom-variant に移行する
• config-preflight-defaults - v4 での Preflight のデフォルト変更に対応する

2. 非推奨ユーティリティの置き換え（CRITICAL）

• dep-opacity-modifiers - -opacity- を不透明度修飾子（/50）に置き換える
• dep-flex-shorthand - flex-shrink／flex-grow を shrink／grow に置き換える
• dep-text-ellipsis - overflow-ellipsis を text-ellipsis に置き換える
• dep-decoration-utilities - decoration-slice／clone を box-decoration-* に置き換える
• dep-transform-composites - transform-none を個別のリセットに置き換える
• dep-transition-properties - transition-[transform] を個別のプロパティに更新する

3. ユーティリティの名称変更に伴う更新（HIGH）

• rename-shadow-scale - シャドウユーティリティを新しいスケールに更新します
• rename-blur-scale - ぼかしユーティリティを新しいスケールに更新します
• rename-rounded-scale - 角丸ユーティリティを新しいスケールに更新します
• rename-ring-width - v3 のデフォルトに合わせて ring を ring-3 に置き換えます
• rename-gradient-utilities - bg-gradient-* を bg-linear-* に置き換えます
• rename-outline-hidden - outline-none を outline-hidden に置き換えます

4. クラスの統合（HIGH）

• class-size-utility - 対応する w-* と h-* を size-* に置き換えます
• class-gap-over-space - flex/grid では space-x/y-* より gap-* を優先します
• class-inset-shorthand - top/right/bottom/left を inset-* に置き換えます
• class-border-color-explicit - v4 のデフォルト変更に合わせて、明示的なボーダー色を追加します
• class-ring-color-explicit - v4 のデフォルト変更に合わせて、明示的なリング色を追加します
• class-redundant-display - 冗長な display クラスを削除します
• class-hidden-priority - hidden 属性に対する display のオーバーライドを削除します
• class-container-utility - container プラグイン設定を @utility に置き換えます

5. 任意値の整理（MEDIUM-HIGH）

• arb-hex-to-theme - 任意の 16 進カラーをテーマトークンに置き換えます
• arb-spacing-to-scale - 任意のスペーシングをテーマスケールに置き換えます
• arb-dynamic-classes - クラス名の動的な構築を避けます
• arb-breakpoint-to-theme - 任意のブレークポイントを @theme に置き換えます
• arb-zindex-to-scale - 任意の z-index を定義済みのスケールに置き換えます

6. 構文のモダナイズ（MEDIUM）

• syntax-css-variable-parens - CSS 変数の構文を角括弧から丸括弧に更新します
• syntax-variant-stacking - バリアントの重ね順を左から右の順に更新します
• syntax-important-modifier - important 修飾子には末尾の ! を使用します
• syntax-grid-arbitrary - グリッドの任意値ではアンダースコアを使用します
• syntax-gradient-preservation - バリアント内でグラデーションの停止位置を明示的にリセットします
• syntax-hover-media-query - hover バリアントがメディアクエリでラップされることを考慮します

7. @apply とアーキテクチャの整理（MEDIUM）

• arch-apply-to-component - @apply ブロックをフレームワークコンポーネントに切り出します
• arch-layer-to-utility - @layer components を @utility に置き換えます
• arch-scoped-reference - スコープ付きスタイルで @apply を使う場合は @reference を使用します
• arch-safelist-to-source - safelist を @source inline() に置き換えます
• arch-domain-composition - Tailwind はプリミティブに限定し、ドメイン向けの要素は組み合わせて構成します

8. 最新機能の採用（LOW-MEDIUM）

• adopt-container-queries - ビューポートのブレークポイントではなく、コンテナークエリを使用します
• adopt-not-variant - 否定条件には not-* バリアントを使用します
• adopt-in-variant - 親の状態に応じたスタイル設定を簡潔にするため、in-* バリアントを使用します
• adopt-field-sizing - テキストエリアを自動でリサイズするには、field-sizing-content を使用します
• adopt-starting-variant - JavaScript を使わずに開始時のアニメーションを実現するには、starting バリアントを使用します

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報