react-tailwind

目的

このスキルを使うと、React プロジェクトを適切に構成された Tailwind ベースの UI にしたり、既存の Tailwind 構成を、より整理されたトークンベースのスタイルと再利用可能なパターンにリファクタリングしたりできます。

次の作業を支援します。

• React のツールチェーンに Tailwind をインストールして組み込む
• 依存関係（Tailwind、プラグイン、コンポーネントライブラリ）を計画・管理する
• tailwind.config にセマンティックなトークンレイヤー（色、余白、タイポグラフィ、角丸、シャドウ）を設計する
• コンポーネントを場当たり的な CSS から Tailwind ユーティリティクラスにリファクタリングする
• 実績のある UI パターン（フォーム、データテーブル、ナビゲーション、モーダル、レイアウトの基本要素）を適用する

ユーザーが、実用的ですぐにコピーして使える手順と、具体的なコンポーネント例を求めているものとして対応してください。

React とビルド構成を特定する

コマンドやコードを提示する前に、アプリのビルド方法を特定し、それに合わせて手順を調整してください。

• package.json に react-scripts がある場合：Create React App として扱います。
• devDependencies またはスクリプトに vite がある場合：Vite React として扱います。
• next がある場合：Next.js として扱います（app/ があれば App Router、なければ Pages Router）。
• react-scripts／vite／next がない場合：webpack などを使う一般的な React SPA として扱い、フレームワークに依存しない案内を提示します。

判断が難しい場合は、Vite に近い Tailwind の構成を既定として、適応方法を明確に説明してください。

• 更新する設定ファイル（tailwind.config.js、postcss.config.js、エントリー CSS）を説明します。
• 必要に応じて、コマンドを npm と yarn の両方で示します。

インストールと設定の手順

React プロジェクトに Tailwind を設定する場合は、必ず次の順序に従ってください。

1. 依存関係を追加する
   • コア：tailwindcss postcss autoprefixer
   • ダークモードとテーマには Tailwind コアを使用します。UI ライブラリ（例：@headlessui/react、@heroicons/react、Radix など）を追加するのは、ユーザーが事前構築済みのパターンを希望する場合に限ります。
   • ビルド時に使うパッケージは、devDependencies に追加することを優先します。
2. Tailwind を初期化する
   • 特定したツールチェーンに推奨される初期化コマンドを実行します（例：npx tailwindcss init -p）。
   • tailwind.config.* と postcss.config.* の両方を作成するか、更新します。
3. content のパスを設定する
   • 次のような React のすべてのソースルートを含めます。
     • ./index.html（Vite の場合）
     • ./src/**/*.{js,ts,jsx,tsx}
     • Next.js の場合は ./app/**/*.{js,ts,jsx,tsx,mdx} および／または ./pages/**/*.{js,ts,jsx,tsx}。
   • node_modules やビルド出力を含む、範囲が広すぎる glob は避けてください。
4. Tailwind を CSS に組み込む
   • グローバル CSS ファイル（例：src/index.css、src/globals.css、app/globals.css）を作成または更新し、次の内容を含めます。
     • @tailwind base;
     • @tailwind components;
     • @tailwind utilities;
   • この CSS がアプリのエントリーポイント（main.tsx、_app.tsx、layout.tsx など）で一度だけインポートされていることを確認します。
5. 組み込みを確認する
   • 簡単なテスト用ユーティリティ（例：className="text-red-500"）を追加し、正しく表示されることを確認するようユーザーに案内します。
   • うまくいかない場合は、次の点を調べます。
     • content のパスが不足していないか
     • CSS がインポートされているか
     • CSS フレームワーク（例：Bootstrap）と競合していないか。移行方法または共存方法を案内してください。

追加の UI ライブラリ（例：Tailwind UI、Headless UI、Radix）をインストールする場合は、必ず次の点に従ってください。

• Tailwind コアが動作してから追加します。
• ピア依存関係（例：React のバージョン、@floating-ui）を確認して説明します。
• インストールコマンドとインポート箇所を明確に示します。

Tailwind の設定とセマンティックトークン

生のブランドカラーや余白をあちこちに散在させるのではなく、セマンティックなテーマレイヤーの設計を目指します。

tailwind.config.* を編集する場合：

• theme.colors と theme.extend.colors は、文字どおりのブランドカラーの HEX 名ではなく、セマンティックな用途ごとに整理します。
• ニュートラル、プライマリ／セカンダリ、フィードバックのスケールを使用します。

// Example shape – adapt values and names to user brand
theme: {
  extend: {
    colors: {
      bg: {
        canvas: '#020617',
        subtle: '#0b1120',
        elevated: '#020617'
      },
      border: {
        subtle: '#1e293b',
        strong: '#475569',
        focus: '#38bdf8'
      },
      text: {
        primary: '#e5e7eb',
        secondary: '#9ca3af',
        muted: '#6b7280',
        danger: '#fecaca'
      },
      primary: {
        DEFAULT: '#38bdf8',
        foreground: '#0f172a',
        soft: '#0ea5e9'
      },
      danger: {
        DEFAULT: '#ef4444',
        subtle: '#fee2e2'
      },
      success: {
        DEFAULT: '#22c55e',
        subtle: '#dcfce7'
      }
    },
    borderRadius: {
      sm: '0.375rem',
      md: '0.5rem',
      lg: '0.75rem',
      xl: '1rem'
    },
    boxShadow: {
      soft: '0 1px 2px 0 rgba(15,23,42,0.35)',
      raised: '0 10px 30px rgba(15,23,42,0.6)'
    }
  }
}

ガイドライン：

• 生のブランド名よりも、用途に基づく名前（bg.canvas、text.secondary、border.focus など）を優先します。
• 既存の CSS 変数がある場合は、動作を維持するために Tailwind のテーマキーに割り当てます。
• ダーク／ライトモードの場合：
  • Tailwind の dark クラス戦略（darkMode: 'class'）を優先します。
  • React の状態または小さなテーマフックを使って、html／body／ルート要素の dark クラスを切り替える方法をユーザーに案内します。

トークンを追加または変更する場合は必ず、それらを使用するコンポーネントのコード例を1つか2つ示し、具体的な使い方がわかるようにします。

コンポーネントの改修ワークフロー

ユーザーが Tailwind でコンポーネントを「改修」または「モダン化」したい場合：

1. コンポーネントを監査する
   • 既存の JSX と CSS を提示するよう依頼するか、内容を確認します。
   • 以下を特定します。
     • レイアウトの基本要素（スタック、グリッド、サイドバー、カード）
     • タイポグラフィの階層（見出し、ラベル、本文）
     • インタラクティブ要素（ボタン、リンク、入力欄）
2. Tailwind の構造を設計する
   • レイアウト用 CSS を Tailwind の基本クラス（flex、grid、gap、space-y-*、max-w-*、overflow-*）に置き換えます。
   • CSS 変数やデザイントークンを Tailwind のテーマキーに割り当てます。
   • 繰り返しのパターンは、小さな再利用可能コンポーネント（例：Button、Card、Input、Modal）にまとめます。
3. 段階的にリファクタリングする
   • 一度に1つのコンポーネント（例：単一のフォーム、カード一覧）から始めます。
   • 動作と props は維持し、JSX の構造とクラスのみを変更します。
4. 共通の構成要素を抽出する
   • クラスの組み合わせが繰り返されている場合は、以下を提案します。
     • className の拡張フックを備えた React コンポーネント。
     • クラス名を組み立てるユーティリティ関数（例：clsx、cva）。
5. アクセシビリティを確認する
   • ロール、aria 属性、フォーカスリングが維持または改善されていることを確認します。
   • セマンティックなボーダー／フォーカストークンを使ったフォーカススタイルを示します。

可能な場合は必ず、変更前と変更後のコード例（古い JSX／CSS と Tailwind を適用した JSX）を提示します。

よくある UI のレシピ

これらのパターンを出発点として使い、ユーザーのテーマに合わせてトークンを調整します。利用可能な場合は、セマンティックな Tailwind トークン（例：bg-bg-elevated、text-text-secondary）を優先します。利用できない場合は、一般的なデフォルト値を使用します。

フォーム

目標：余白を統一し、ラベルと入力欄の配置を明確にし、アクセシブルなフォーカススタイルと役立つエラーテキストを用意します。

フォームのパターン：

• 各フィールドを、小さな gap を使った縦方向のスタックで囲みます。
• htmlFor を指定したラベルを使い、タイポグラフィを統一します。
• 入力欄には以下を適用します。
  • 幅いっぱいに広げる w-full
  • セマンティックな背景、ボーダー、フォーカストークン
  • 適切に角丸と控えめなシャドウを付ける

リファクタリング時は、以下を確認します。

• エラー状態には、セマンティックな危険状態トークン（例：border-danger、text-danger）を使います。
• 無効状態では不透明度を下げ、ホバースタイルを無効にします。

データテーブル

目標：読みやすい行、適切な密度の調整、明確な並べ替え／選択の視覚的な手がかりを実現します。

テーブルのパターン：

• スクロール用のラッパーに、レスポンシブなパディングと overflow-x-auto を設定します。
• テーブルの基本クラス：min-w-full divide-y divide-border-subtle。
• ヘッダー：
  • ほどよいコントラストの背景（例：bg-bg-subtle）を設定します。
  • 必要に応じて、トラッキングを付けた大文字またはスモールキャップを使います。
  • 視覚的なノイズを抑えるため、text-text-secondary を使います。
• 行：
  • divide-y divide-border-subtle を設定します。
  • ホバー時：hover:bg-bg-subtle/60。
  • 選択時：bg-primary/5 border-l-2 border-primary。

行内のアクションには、以下を推奨します。

• アクセシブルなラベル付きのインラインアイコンボタン。
• 明確な間隔（space-x-2）と十分なタッチ領域（p-1.5～p-2）。

ナビゲーション（トップバー＋サイドバー）

ナビゲーションのレイアウト：

• シェルレイアウトを使用します。
  • トップバー：flex items-center justify-between h-14 px-4 border-b border-border-subtle bg-bg-elevated。
  • サイドバー（任意）：hidden md:flex md:w-64 md:flex-col border-r border-border-subtle bg-bg-subtle。
  • メイン領域：flex-1 overflow-y-auto p-4 md:p-6。

ナビゲーション項目：

• 基本：flex items-center gap-2 rounded-md px-2.5 py-2 text-sm font-medium。
• デフォルトのテキスト：text-text-secondary。
• アクティブ：bg-bg-elevated text-text-primary。
• ホバー：hover:bg-bg-elevated/70 hover:text-text-primary。

ナビゲーションは、設定オブジェクト（ラベル、アイコン、href、アクティブ状態）の配列にまとめて、JSX でマッピングする方法がおすすめです。後からスタイルを変更しやすくなります。

モーダル／ダイアログ

アクセシブルなモーダルを実装する場合：

• 可能であれば、ヘッドレスライブラリまたはプリミティブベースのライブラリ（例：@headlessui/react や Radix Dialog）の使用をおすすめします。
• 手動で実装する場合は、次の点を必ず含めてください。
  • ARIA ロール（role="dialog"、aria-modal="true"）。
  • フォーカストラップと Escape キーの処理。
  • 透明度を設定した背景オーバーレイ。

スタイル：

• オーバーレイ：fixed inset-0 bg-black/60 backdrop-blur-sm。
• コンテナ：fixed inset-0 flex items-center justify-center px-4。
• パネル：
  • w-full max-w-lg rounded-lg bg-bg-elevated shadow-raised p-6
  • トークン化された色と余白を使用します。

モーダル内のボタンには、場当たり的なクラスではなく、アプリのプライマリ／セカンダリボタンコンポーネントを再利用してください。

依存関係の管理とインストール順序

ユーザーから「Tailwind をセットアップする」または「Tailwind コンポーネントを追加する」と依頼された場合は、操作の順序を明確に示してください。

1. React とバンドラーの依存関係がすでにインストールされていることを確認します（React、ReactDOM、フレームワーク固有のツールなど）。
2. Tailwind、PostCSS、Autoprefixer を devDependencies としてインストールします。
3. Tailwind 設定と PostCSS 設定を初期化します。
4. アプリのエントリーポイントに Tailwind CSS を組み込み、動作を確認します。
5. 依頼された場合は、コンポーネントライブラリまたはヘッドレスプリミティブを導入します。
   • ライブラリをインストールします。
   • 必要に応じてスタイルをインポートします（ライブラリによっては基本 CSS が含まれています）。
   • Tailwind クラスやテーマトークンとの統合方法を示します。
6. 既存のコンポーネントを段階的にリファクタリングします。次の順に進めます。
   • ボタンとタイポグラフィ。
   • フォーム。
   • レイアウトシェル（ナビゲーション、サイドバー、メインコンテンツ）。
   • データ量の多いビュー（テーブル、リスト、詳細パネル）。

推奨内容に合わせて package.json を常に更新し、関連する場合は必要な Node または React のバージョンを明記してください。

よくある問題と対処方法

Tailwind と React のセットアップをデバッグするときは、次の問題を確認してください。

• クラスが適用されない
  • content の glob がファイルパスまたは拡張子と一致していない。
  • @tailwind ディレクティブを含む CSS ファイルがどこからもインポートされていない。
  • ビルドキャッシュ。開発サーバーの再起動またはキャッシュのクリアを提案します。
• 本番ビルドでスタイルが適用されない、または一部しか適用されない
  • content のパスが正しくないため、過剰なパージが発生している。
  • Purge が検出できない方法でクラスを動的に構築している。次を推奨します。
    • コード内で標準的なクラス名を使用します。
    • 任意の入力から完全な文字列を構築するのではなく、バリアント用のクラスマップを切り出します。
• 他のフレームワークとの競合
  • レガシーなグローバル CSS（例：Bootstrap）が Tailwind を上書きしている。次を提案します。
    • 競合するインポートを段階的に削除します。
    • 可能であれば、レガシー CSS に名前空間を付けます。
• デザインに一貫性がない
  • 場当たり的な色や余白が繰り返し使われている。次を提案します。
    • Tailwind のセマンティックトークンにまとめます。
    • 繰り返し使われるクラス群を共通コンポーネントにリファクタリングします。

問題を修正または診断したら、ユーザーが次回も再実行できる短いチェックリストを提示してください（例：「設定パス、CSS のインポート、開発サーバーの再起動を確認する」）。