tailwind-css

Tailwind CSS 4.x

プラットフォーム： Web（Tailwind CSS 4.x）。モバイルのスタイリングについては、nativewind スキル（React Native 向け Tailwind 3.x）を参照してください。

概要

迅速な UI 開発のためのユーティリティファーストな CSS フレームワークです。Tailwind CSS 4.x では、CSS ファーストの設定方式、自動コンテンツ検出、新しいエンジンによるパフォーマンスの向上が導入されています。

インストール： pnpm add -D tailwindcss @tailwindcss/vite

API リファレンス： ユーティリティクラスの全リファレンスについては、Context7 MCP（mcp__context7__resolve-library-id → tailwindcss）を使用してください。

v4 の主な変更点

• CSS ファーストの設定 - tailwind.config.js の代わりに CSS で @theme を使用します
• 単一のインポート - 個別のディレクティブの代わりに @import "tailwindcss" を使用します
• 自動コンテンツ検出 - content 配列は不要です
• 新しいカラーシステム - 広色域に対応した OKLCH カラー
• 組み込みの Vite プラグイン - 最適な統合のための @tailwindcss/vite

ワークフロー

Tailwind v4 のセットアップ：

1. 依存関係をインストールします：pnpm add -D tailwindcss @tailwindcss/vite
2. Vite プラグインを vite.config.ts に追加します
3. @import "tailwindcss" を記述した index.css を作成します
4. @theme ディレクティブでテーマをカスタマイズします
5. ビルドプロセスをテストし、スタイルが読み込まれることを確認します

コンポーネントの作成：

1. セマンティックな HTML 構造から始めます
2. レイアウトにユーティリティクラス（flex、grid）を適用します
3. 余白のユーティリティ（p-、m-、gap-*）を追加します
4. 色、タイポグラフィ、境界線を設定します
5. レスポンシブバリアント（sm:、md:、lg:）を追加します
6. 複数のビューポートでテストします

カスタムテーマ：

1. CSS で @theme を使用してデザイントークンを定義します
2. カスタムカラー、余白、フォントを追加します
3. セマンティックなカラーエイリアスを作成します
4. トークンが各コンポーネントで機能することを確認します

設定

Vite の設定

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

CSS エントリーポイント

/* src/index.css */
@import "tailwindcss";

@theme {
  /* Brand colors (OKLCH for wide gamut) */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.6 0.15 300);
  --color-success: oklch(0.7 0.2 150);
  --color-warning: oklch(0.8 0.15 85);
  --color-danger: oklch(0.6 0.25 25);

  /* Typography */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "Fira Code", monospace;

  /* Custom spacing */
  --spacing-128: 32rem;

  /* Custom animations */
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

/* Dark mode variant */
@variant dark (&:where(.dark, .dark *));

レスポンシブデザイン

デフォルトのブレークポイント（モバイルファースト）：sm: 640px | md: 768px | lg: 1024px | xl: 1280px | 2xl: 1536px

// Stack on mobile, grid on desktop
<div className="flex flex-col md:flex-row gap-4">
  <div className="w-full md:w-1/2">Left</div>
  <div className="w-full md:w-1/2">Right</div>
</div>

// Responsive grid
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
  {items.map(item => <div key={item.id} className="rounded-lg border p-4">{item.content}</div>)}
</div>

// Responsive typography
<h1 className="text-2xl sm:text-3xl md:text-4xl lg:text-5xl">Scales with viewport</h1>

// Show/hide at breakpoints
<div className="hidden lg:block">Desktop only</div>
<div className="block lg:hidden">Mobile only</div>

カスタムブレークポイント：@theme に --breakpoint-demo: 1440px; を追加します。

ダークモード

function App() {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => { document.documentElement.classList.toggle('dark', isDark); }, [isDark]);
  return (
    <div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
      <button onClick={() => setIsDark(!isDark)}>Toggle Dark Mode</button>
    </div>
  );
}

コンポーネントパターン

ボタン

// Primary
<button className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
  Primary
</button>

// Secondary
<button className="rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500 transition-colors">
  Secondary
</button>

カード

// Basic card
<div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
  <h3 className="text-lg font-semibold text-gray-900">Card Title</h3>
  <p className="mt-2 text-sm text-gray-600">Description</p>
</div>

// Card with header/footer
<div className="rounded-lg border border-gray-200 bg-white overflow-hidden">
  <div className="border-b border-gray-200 bg-gray-50 px-6 py-4">
    <h3 className="text-lg font-semibold text-gray-900">Header</h3>
  </div>
  <div className="p-6"><p className="text-sm text-gray-600">Content</p></div>
  <div className="border-t border-gray-200 bg-gray-50 px-6 py-4">
    <button className="text-sm font-medium text-blue-600 hover:text-blue-700">Action</button>
  </div>
</div>

フォーム入力

<div className="space-y-1">
  <label htmlFor="email" className="block text-sm font-medium text-gray-700">Email</label>
  <input
    type="email"
    id="email"
    className="block w-full rounded-md border border-gray-300 px-3 py-2 text-sm placeholder-gray-400 shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
    placeholder="[email protected]"
  />
</div>

高度なパターン

バリアント修飾子

// Group hover — child reacts to parent hover
<div className="group hover:bg-gray-100">
  <h3 className="group-hover:text-blue-600">Changes on parent hover</h3>
</div>

// Peer — sibling state
<input type="checkbox" className="peer" />
<label className="peer-checked:text-blue-600">Changes when checked</label>

// Data attributes
<div data-state="active" className="data-[state=active]:bg-blue-100">Active state</div>

// Structural: first:, last:, odd:, even:
<li className="first:rounded-t-lg last:rounded-b-lg border-b last:border-b-0">Item</li>

任意の値とカスタムユーティリティ

// Arbitrary values with []
<div className="top-[117px] bg-[#1da1f2] grid-cols-[1fr_500px_2fr]">Custom values</div>
<div className="w-[calc(100%-2rem)] bg-[var(--brand-color)]">CSS var + calc</div>

/* Custom utilities with @utility */
@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
  &::-webkit-scrollbar { display: none; }
}

v3 からの移行

v3 のパターン	v4 のパターン
tailwind.config.js	CSS の @theme
@tailwind base; など	@import "tailwindcss"
content: [...]	自動検出
PostCSS プラグイン	@tailwindcss/vite プラグイン

手順： 新しいパッケージをインストール → PostCSS 設定を Vite プラグインに置き換える → @tailwind ディレクティブを置き換える → テーマを @theme に移す → content 配列を削除する → テストする。

ベストプラクティス

• モバイルファーストのアプローチ - 基本スタイルから始め、レスポンシブバリアントを追加します
• セマンティックなカラー名を使用する - @theme で primary、secondary、danger を設定します
• クラスを整理する - レイアウト → 余白 → 色 → タイポグラフィ → 状態
• 任意の値は控えめに使用する - テーマトークンを優先します
• group- と peer- のユーティリティで** hover/focus の状態をグループ化します
• Vite プラグインを使用する - 最高のパフォーマンスを得るには @tailwindcss/vite を使用します

アンチパターン

• カスタマイズに tailwind.config.js を使用する（@theme を使用してください）
• @tailwind ディレクティブを使用する（@import "tailwindcss" を使用してください）
• content 配列を手動で設定する（v4 では自動検出されます）
• Vite で PostCSS プラグインを使用する（@tailwindcss/vite を使用してください）
• デスクトップファーストのレスポンシブデザイン（モバイルに適していません）
• テーマトークンを使用せずに色をハードコードする
• アクセシビリティを無視する（フォーカス状態が不足しています）

フィードバックループ

# Check generated CSS size (target < 50KB)
pnpm build

# Watch for changes
pnpm dev

インタラクティブ要素を Tab キーで移動して、フォーカス状態をテストします。focus:ring-* ユーティリティが表示されることを確認します。ブラウザーの開発者ツールで色のコントラストを確認します。