converting-css-modules-to-tailwind

CSS Modules を Tailwind に変換する

コンポーネントを CSS Modules（.module.css / .module.scss）から Tailwind のユーティリティクラスに移行します。

ワークフロー

1. モジュールを調査する

.module.css ファイルと、それをインポートしているコンポーネントを読みます。すべての styles.xxx 参照を、対応する CSS ルールに関連付けます。

// Before
import styles from './Card.module.css';
<div className={styles.card}>
  <h2 className={styles.title}>{title}</h2>
  <p className={styles.body}>{children}</p>
</div>

/* Card.module.css */
.card { display: flex; flex-direction: column; gap: 16px; padding: 24px; border-radius: 12px; background: white; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
.title { font-size: 20px; font-weight: 600; color: #111827; }
.body { font-size: 14px; color: #6b7280; line-height: 1.6; }

2. 各クラスを変換する

styles.xxx を同等の Tailwind ユーティリティに置き換えます。

// After
<div className="flex flex-col gap-4 p-6 rounded-xl bg-white shadow-sm">
  <h2 className="text-xl font-semibold text-gray-900">{title}</h2>
  <p className="text-sm text-gray-500 leading-relaxed">{children}</p>
</div>

3. CSS Modules のパターンに対処する

composes キーワード：

.base { padding: 8px 16px; border-radius: 4px; }
.primary { composes: base; background: blue; color: white; }

→ 1 つのユーティリティセットにまとめます。再利用が必要な場合は、クラスではなくコンポーネントを抽出します。

clsx / classnames を使った条件付き className：

// Before
className={clsx(styles.button, isActive && styles.active)}
// After
className={clsx("px-4 py-2 rounded", isActive && "bg-blue-600 text-white")}

動的なクラス選択：

// Before
className={styles[variant]}
// After — use a lookup object
const variantClasses = {
  primary: "bg-blue-600 text-white hover:bg-blue-700",
  secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
  danger: "bg-red-600 text-white hover:bg-red-700",
};
className={variantClasses[variant]}

CSS Modules のグローバルなオーバーライド：

:global(.some-library-class) { ... }

→ @layer components { } を使って globals.css に移すか、グローバルスタイルシートで Tailwind の @apply を使います。

SCSS の機能（ネスト、変数、ミックスイン）：

• ネストされたセレクター → 各要素のユーティリティクラスに展開します
• SCSS の $variables → tailwind.config.ts のテーマ値に対応付けます
• ミックスイン → ユーティリティの組み合わせに置き換えるか、コンポーネントを抽出します

4. クリーンアップする

1. import styles from './Xxx.module.css' の行を削除します
2. .module.css / .module.scss ファイルを削除します
3. コンポーネントと同じ場所にある index.ts のバレルファイルがスタイルを再エクスポートしていた場合は、更新します
4. 削除したモジュールをインポートしている箇所がほかにないか、コードベースを検索します
5. アプリを実行して視覚的に確認し、リグレッションがないか確認します

ルール

• コンポーネントは一度に 1 つずつ変換します。ディレクトリ全体をまとめて変換しないでください
• 条件付きロジックは CSS ではなく、clsx() またはテンプレートリテラルに記述します
• モジュールに疑似要素のスタイル（content を伴う :before、:after）がある場合は、Tailwind で before: / after: プレフィックスと content-['...'] が必要です
• :nth-child、:first-of-type などについては、Tailwind に対応するバリアントがあるか確認し、なければ最小限の CSS ルールを残します
• モジュールの動作を再現するために @apply クラスを作成しないでください。目的は間接性をなくすことです