tailwind-ui-refactor

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

Adam Wathan と Steve Schoger による Refactoring UI に基づき、Tailwind CSS のユーティリティクラスを使って実装する、包括的な UI リファクタリングガイドです。9 つのカテゴリにわたる 52 のルールをデザインへの影響度順に整理し、自動リファクタリングとコード生成の指針を示します。Tailwind CSS v4 の構文を使用しています（構文が異なる場合は v3 の注記を記載しています）。

重要：まず考え、スタイルはそのあとです。 見た目に関するルールを適用する前に、UI の目的を理解し、ユーザーにとって重要な要素を特定して、不要な要素を取り除いてください。スタイルを変更する前に、Design Intent カテゴリ（優先度 1）を必ず検討してください。要素が少ないシンプルなコンポーネントは、不要なマークアップを装飾したコンポーネントより常に優れています。

適用するタイミング

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

• 既存の Tailwind CSS コンポーネントをリファクタリングするとき
• Tailwind のユーティリティクラスを使って新しい UI を作成するとき
• 視覚的な階層や余白の問題についてコードをレビューするとき
• デザイナーがいない環境でデザインの品質を高めるとき
• アクセシビリティに関するコントラストの問題を修正するとき

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

優先度	カテゴリ	影響度	プレフィックス
1	デザイン意図	重大	intent-
2	視覚的な階層	重大	hier-
3	レイアウトと余白	重大	space-
4	タイポグラフィ	高	type-
5	カラーシステム	高	color-
6	奥行きとシャドウ	中	depth-
7	境界線と区切り	中	sep-
8	画像とコンテンツ	低〜中	img-
9	仕上げと細部	低	polish-

クイックリファレンス

1. デザイン意図（重大）

• intent-audit-before-styling - CSS を変更する前に、各要素が何を伝えているかを確認する
• intent-remove-before-decorating - 残す要素をスタイリングする前に、不要な要素を取り除く
• intent-reduce-cognitive-load - 画面ごとの選択肢を減らす — 選択肢は、見栄えの良さより少ないことが重要
• intent-progressive-disclosure - 副次的な情報は操作の背後に隠す
• intent-content-drives-layout - レイアウトをコンテンツに合わせる — その逆ではない
• intent-simplify-over-decorate - ラッパーにユーティリティクラスを 5 つ追加するより、ラッパーを取り除く
• intent-match-context-fidelity - 文脈に合わせてデザインの作り込みを調整する — 管理画面、一般消費者向け、製品など
• intent-match-existing-patterns - スタイルを変更する前に、同階層のコンポーネントのパターンを確認する

2. 視覚的な階層（重大）

• hier-size-weight-color - 階層にはサイズだけでなく、サイズ、太さ、色を使う
• hier-deemphasize-secondary - 主情報を強調するのではなく、副次的なコンテンツを目立たなくする
• hier-button-hierarchy - 意味上の重要度ではなく、視覚的な階層に合わせてボタンをスタイリングする
• hier-label-value-pairs - ラベルと値を自然な言葉にまとめる
• hier-semantic-vs-visual - 視覚的な階層と文書の階層を分ける
• hier-icon-sizing - 空間を埋めるのではなく、隣接するテキストに合わせてアイコンのサイズを決める
• hier-color-hierarchy-on-dark - 色付きの背景では、不透明度や控えめな色を使って階層を表現する

3. レイアウトと間隔（重要）

• space-start-generous - 余白を多めに取り、そこから減らしていきます
• space-systematic-scale - 任意の値ではなく、制約のある間隔のスケールを使います
• space-relationship-proximity - 要素間の関係を示すために間隔を使います
• space-dont-fill-screen - コンテンツの幅を制限し、画面全体を埋めないようにします
• space-grids-not-required - グリッドが不要な場合は固定幅を使います
• space-relative-sizing-fails - 上限・下限を設定せずにビューポート単位をそのまま使うのは避けます
• space-mobile-first - 約400pxのモバイル向けから設計し、その後広げていきます

4. タイポグラフィ（高）

• type-line-length - 行の長さを45～75文字に保ちます
• type-line-height-inverse - 行の高さとフォントサイズは反比例します
• type-font-weight-variety - 5種類以上のウェイトを備えたフォントを選びます
• type-no-center-long-text - 本文は左揃えにし、長文の中央揃えは避けます
• type-letter-spacing - 見出しでは文字間隔を詰め、大文字では広げます
• type-align-numbers-right - 比較しやすいよう、表の数値は右揃えにします

5. カラーシステム（高）

• color-define-palette-upfront - その場しのぎで色を選ばず、最初に完全なカラーパレットを定義します
• color-grayscale-first - まずグレースケールでデザインし、最後に色を加えます
• color-accessible-contrast - 本文のコントラスト比を4.5:1以上にします
• color-dark-gray-not-black - テキストには純粋な黒ではなく、濃いグレーを使います
• color-saturated-grays - グレーに控えめな彩度を加え、暖色系または寒色系の印象にします
• color-light-backgrounds-dark-text - バッジには明るい背景色と暗いテキストを使います

6. 奥行きとシャドウ（中）

• depth-shadow-scale - 小から特大まで、固定のシャドウスケールを定義します
• depth-shadow-vertical-offset - 自然な見た目のシャドウには垂直方向のオフセットを使います
• depth-interactive-elevation - シャドウの変化で操作可能であることを伝えます
• depth-light-closer-dark-recedes - 明るい色は手前に、暗い色は奥に感じられます
• depth-overlap-layers - 要素を重ねて視覚的なレイヤーを作ります

7. 境界線と区切り（中）

• sep-fewer-borders - 境界線を減らし、間隔、シャドウ、背景色で置き換えます
• sep-background-color-separation - 背景色の違いを使ってセクションを区切ります
• sep-table-spacing-not-lines - シンプルな表では線ではなく間隔を使います
• sep-card-radio-buttons - 重要な選択肢では、ラジオボタンを選択可能なカードに置き換えます

8. 画像とコンテンツ（低〜中）

• img-control-user-content - ユーザーがアップロードした画像のサイズとアスペクト比を制御します
• img-text-overlay - 画像上のテキストにオーバーレイを追加するか、コントラストを下げます
• img-dont-scale-up-icons - 小さいサイズ向けにデザインされたアイコンを拡大しないようにします
• img-empty-states - 明確な CTA を含む、意味のある空の状態をデザインします

9. 仕上げと細部（低）

• polish-accent-borders - アクセントボーダーを追加して重要な要素を強調します
• polish-custom-bullets - デフォルトの箇条書きをアイコンやチェックマークに置き換えます
• polish-border-radius-personality - ボーダーの角丸をブランドの個性に合わせます
• polish-gradient-close-hues - 色相が互いに 30 度以内のグラデーションを使用します
• polish-inner-shadow-images - 画像の背景がにじむのを防ぐため、内側の影を追加します

範囲と制限事項

このスキルでは、Refactoring UI の原則に基づくレイアウト、階層、余白、色、仕上げを扱います。以下は対象外です。

• フォントの選定と組み合わせ — 個性のある書体の選び方、汎用的な AI のデフォルト（Inter、Arial、system-ui）の回避、見出し用フォントと本文用フォントの組み合わせ
• アニメーションとモーション — 意味のあるトランジション、マイクロインタラクション、ページ読み込み時のシーケンス、スクロールをきっかけに表示する演出
• クリエイティブディレクション — 美的ビジョンの確立、トーン（ミニマル、マキシマリスト、ブルータリストなど）の選択、汎用的な「AI スロップ」風の美学との差別化
• 空間構成 — 非対称なレイアウト、グリッドを崩す要素、型破りなビジュアルフロー

これらの課題には、クリエイティブディレクションと美的表現を扱うデザイン思考またはフロントエンドデザインのスキルを併用してください。

使用方法

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

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

リファレンスファイル

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