tailwind-best-practices

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

Tailwind CSS v3.4+ および v4 を使用して、一貫性があり保守しやすいインターフェースを構築するための包括的なパターンです。レスポンシブデザイン、ダークモード、コンポーネントのパターン、設定、v4 への移行に関する 29 のルールを収録しています。

メタデータ

• バージョン: 1.0.0
• フレームワーク: Tailwind CSS v3.4+ / v4.0+
• ルール数: 8 カテゴリにわたる 29 のルール
• ライセンス: MIT
• ドキュメント: tailwindcss.com/docs

ステップ 1: Tailwind のバージョンを確認する

アドバイスをする前に、必ずバージョンを確認してください。 v3 と v4 は根本的に異なります。

インストールされているバージョンを package.json で確認します。

{ "tailwindcss": "^3.x" }  // → v3 rules apply
{ "tailwindcss": "^4.x" }  // → v4 rules apply

次の手がかりも確認してください。

手がかり	バージョン
tailwind.config.js が存在する	v3
CSS に @import "tailwindcss" がある	v4
依存関係に @tailwindcss/vite がある	v4
依存関係に @tailwindcss/postcss がある	v4
CSS に @theme {} ブロックがある	v4

v3 の場合：resp-、dark-、comp-、config- ルールを適用します。v4 が利用可能であることにも注意してください。 v4 の場合：v4- ルールを適用します。tailwind.config.js のパターンは適用されないため、代わりに @theme {} を使用します。 v3 から v4 に移行する場合：v4-migration ルールに従ってください。

適用する場面

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

• レスポンシブレイアウトを作成するとき
• ダークモードを実装するとき
• 再利用可能なコンポーネントスタイルを作成するとき
• Tailwind を設定するとき（v3 または v4）
• プロジェクトを v3 から v4 に移行するとき
• v4 で新しいプロジェクトをセットアップするとき

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

優先度	カテゴリ	影響度	プレフィックス	バージョン
1	レスポンシブデザイン	CRITICAL	resp-	v3 / v4
2	ダークモード	CRITICAL	dark-	v3 / v4
3	コンポーネントのパターン	HIGH	comp-	v3 / v4
4	カスタム設定	HIGH	config-	v3
5	V4 と移行	HIGH	v4-	v4 のみ
6	スペーシングとタイポグラフィ	MEDIUM	space-	v3 / v4
7	アニメーション	MEDIUM	anim-	v3 / v4
8	パフォーマンス	LOW	perf-	v3 / v4

クイックリファレンス

1. レスポンシブデザイン（CRITICAL）

• resp-mobile-first - モバイルファーストのアプローチ
• resp-breakpoints - ブレークポイントを正しく使用する
• resp-container - コンテナのパターン
• resp-grid-flex - Grid と Flexbox の使い分け
• resp-hidden-shown - 条件付き表示

2. ダークモード（CRITICAL）

• dark-setup - ダークモードを設定する
• dark-classes - ダークモードのクラスを適用する
• dark-toggle - ダークモードの切り替えを実装する
• dark-system-preference - システム設定を尊重する
• dark-colors - 両方のモードに対応したデザイン

3. コンポーネントのパターン（HIGH）

• comp-clsx-cn - 条件付きクラスのユーティリティ
• comp-variants - コンポーネントのバリアントパターン
• comp-slots - スロットベースのコンポーネント
• comp-composition - ユーティリティの組み合わせ

4. カスタム設定 — v3 のみ（HIGH）

• config-extend - テーマの拡張と上書き
• config-colors - カスタムカラーパレット
• config-fonts - カスタムフォント
• config-screens - カスタムブレークポイント
• config-plugins - プラグインの使用

5. V4 と移行（HIGH）

• v4-installation - Vite または PostCSS、@source、@reference を使用した v4 のインストール
• v4-theme-configuration - tailwind.config.js を CSS 内の @theme {} に置き換える
• v4-custom-utilities - @utility、@custom-variant、@variant、@plugin
• v4-migration - 名前変更されたユーティリティ、starting:、forced-colors: を含む、v3 から v4 への段階的な移行

6. スペーシングとタイポグラフィ（MEDIUM）

• space-consistent - 一貫性のあるスペーシングスケール
• space-margins - マージンのパターン
• space-padding - パディングのパターン
• typo-scale - タイポグラフィのスケール
• typo-line-height - 行の高さ

7. アニメーション（MEDIUM）

• anim-transitions - トランジションのユーティリティ
• anim-keyframes - カスタムキーフレーム
• anim-reduced-motion - 動きの設定を尊重する

8. パフォーマンス（LOW）

• perf-purge - コンテンツの設定
• perf-jit - JIT モードの利点
• perf-arbitrary - 任意の値の使用

基本的なパターン

モバイルファーストのレスポンシブデザイン

// ✅ Mobile-first: start with mobile, add larger breakpoints
<div className="
  w-full           // Mobile: full width
  md:w-1/2         // Tablet: half width
  lg:w-1/3         // Desktop: third width
">
  <p className="
    text-sm          // Mobile: small text
    md:text-base     // Tablet: base text
    lg:text-lg       // Desktop: large text
  ">
    Content
  </p>
</div>

// ❌ Don't think desktop-first
<div className="w-1/3 md:w-1/2 sm:w-full">  // Confusing

ダークモードの実装

v3 — tailwind.config.js：

module.exports = { darkMode: 'class' }

v4 — CSS のみで設定し、設定ファイルは不要です：

@import "tailwindcss";
/* dark mode is class-based by default in v4 — no config needed */

コンポーネント — どちらのバージョンでも同じです：

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  <h2 className="text-gray-900 dark:text-white">Title</h2>
  <p className="text-gray-600 dark:text-gray-400">Description</p>
</div>

function toggleDarkMode() {
  document.documentElement.classList.toggle('dark')
}

clsx/cn による条件付きクラス

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

// cn utility - merges Tailwind classes intelligently
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

// Usage
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  className?: string
  children: React.ReactNode
}

function Button({ variant = 'primary', size = 'md', className, children }: ButtonProps) {
  return (
    <button
      className={cn(
        // Base styles
        'inline-flex items-center justify-center rounded-md font-medium transition-colors',
        'focus:outline-none focus:ring-2 focus:ring-offset-2',

        // Variants
        {
          'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500':
            variant === 'primary',
          'bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-500':
            variant === 'secondary',
          'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500':
            variant === 'danger',
        },

        // Sizes
        {
          'px-3 py-1.5 text-sm': size === 'sm',
          'px-4 py-2 text-base': size === 'md',
          'px-6 py-3 text-lg': size === 'lg',
        },

        // Allow override
        className
      )}
    >
      {children}
    </button>
  )
}

テーマ設定 — v3 と v4 の比較

v3 — tailwind.config.js：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./resources/**/*.{blade.php,js,ts,jsx,tsx}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: { primary: { 500: '#0ea5e9', 600: '#0284c7' } },
      fontFamily: { sans: ['Inter', 'sans-serif'] },
      spacing: { '18': '4.5rem' },
    },
  },
  plugins: [require('@tailwindcss/forms')],
}

v4 — app.css のみで設定し、JS 設定は不要です：

@import "tailwindcss";

@theme {
  --color-primary-500: #0ea5e9;
  --color-primary-600: #0284c7;
  --font-sans: Inter, sans-serif;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 1920px;
}

詳細については、v4-theme-configuration と v4-migration のルールを参照してください。

レスポンシブなグリッドレイアウト

// Product grid - responsive columns
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
  {products.map(product => (
    <ProductCard key={product.id} product={product} />
  ))}
</div>

// Dashboard layout - sidebar + main
<div className="flex flex-col lg:flex-row min-h-screen">
  <aside className="
    w-full lg:w-64
    bg-gray-900
    lg:min-h-screen
  ">
    <nav>...</nav>
  </aside>
  <main className="flex-1 p-4 lg:p-8">
    <div className="max-w-7xl mx-auto">
      {children}
    </div>
  </main>
</div>

フォームのスタイリング

<form className="space-y-6">
  <div>
    <label htmlFor="email" className="block text-sm font-medium text-gray-700 dark:text-gray-300">
      Email
    </label>
    <input
      type="email"
      id="email"
      className="
        mt-1 block w-full rounded-md
        border-gray-300 dark:border-gray-600
        bg-white dark:bg-gray-800
        text-gray-900 dark:text-white
        shadow-sm
        focus:border-blue-500 focus:ring-blue-500
        disabled:bg-gray-100 disabled:cursor-not-allowed
      "
    />
  </div>

  <button
    type="submit"
    className="
      w-full flex justify-center
      py-2 px-4
      border border-transparent rounded-md
      shadow-sm text-sm font-medium
      text-white bg-blue-600
      hover:bg-blue-700
      focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500
      disabled:opacity-50 disabled:cursor-not-allowed
    "
  >
    Submit
  </button>
</form>

モーション低減に対応したアニメーション

// Respect user's motion preferences
<div className="
  transition-transform duration-300
  hover:scale-105
  motion-reduce:transition-none
  motion-reduce:hover:transform-none
">
  Card content
</div>

// Custom animation
<div className="animate-fade-in motion-reduce:animate-none">
  Content
</div>

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      keyframes: {
        'fade-in': {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
      },
      animation: {
        'fade-in': 'fade-in 0.3s ease-out',
      },
    },
  },
}

使用方法

必ず最初にステップ 1（バージョン検出）を実行してから、該当するルールファイルを読み込んでください。

v3 プロジェクト：

rules/config-extend-theme.md
rules/dark-setup.md
rules/comp-clsx-cn.md
rules/resp-mobile-first.md

v4 プロジェクト：

rules/v4-installation.md
rules/v4-theme-configuration.md
rules/v4-custom-utilities.md

v3 から v4 への移行：

rules/v4-migration.md

参考資料

• Tailwind CSS ドキュメント - 公式ドキュメント
• レスポンシブデザインガイド - モバイルファーストのパターン
• ダークモードガイド - テーマの実装
• 設定ガイド - カスタマイズ
• Tailwind UI - 公式コンポーネントライブラリ
• Headless UI - アクセシブルなコンポーネント
• Heroicons - アイコンライブラリ

エコシステムツール

• Tailwind CSS IntelliSense - VS Code のオートコンプリートとリンティング
• Prettier Plugin - クラスの自動並べ替え
• tailwind-merge - 競合しないクラスのマージ
• clsx - 条件付きクラスのユーティリティ
• CVA - コンポーネントのバリアントシステム

ライセンス

MIT ライセンス - ライセンス全文についてはリポジトリを参照してください。

このスキルは Agent Skills コレクションの一部であり、業界のベストプラクティスに基づく AI 活用型の開発支援を提供します。