tailwind

Tailwind CSS（v4 以降）

概要

CSS ファーストの設定、デザイントークン、コンポーネントパターン、shadcn/ui との統合、ダークモード、コンテナクエリ、v3 からの移行、カスタムユーティリティを網羅した Tailwind CSS v4 スキルです。

使用する場合： Tailwind のテーマ設定、ユーティリティファーストのコンポーネント構築、ダークモードの実装、コンテナクエリの使用、v3 からの移行、shadcn/ui との統合、ビルドエラーのトラブルシューティング。

使用しない場合： アップグレード予定のない Tailwind v3 のレガシープロジェクト、Tailwind を採用する予定がなく、別のスタイリング手法（CSS Modules、styled-components）を使用するプロジェクト。

クイックリファレンス

パターン	API	主なポイント
CSS ファースト設定	@theme { --color-brand: oklch(...); }	すべての設定を CSS に記述し、tailwind.config.js は不要です
インポートエントリー	@import "tailwindcss";	@tailwind base/components/utilities を置き換えます
カスタムユーティリティ	@utility name { ... }	@layer utilities を置き換え、バリアントにも対応します
関数型ユーティリティ	@utility tab-* { tab-size: --value(--tab-size-*); }	--value() で動的な値を受け付けます
プラグインの読み込み	@plugin "@tailwindcss/typography";	設定ファイル内の require() を置き換えます
コンテナークエリー	親の @container ＋ 子の @md:	組み込みのため、プラグインは不要です
名前付きコンテナー	@container/sidebar ＋ @md/sidebar:	特定のコンテナーにクエリーのスコープを設定します
ダークモードバリアント	@custom-variant dark (&:where(.dark, .dark *));	クラスベースのダークモードを上書きします
インラインテーマ	@theme inline { --color-bg: var(--bg); }	ビルド時に値をインライン化します。単一テーマのみです
ソース検出	@source "../node_modules/my-lib";	スキャン対象のパスを明示的に追加します
参照インポート	@reference "../../app.css";	Vue／Svelte のスコープ付きスタイルでテーマを使用します
デフォルト値の上書き	@theme 内の --color-*: initial;	再定義の前にカテゴリをリセットします
動的な値	grid-cols-(--my-var)	ユーティリティの値に CSS 変数を使用します
テキストシャドウ	text-shadow-*	組み込みのテキストシャドウユーティリティ
開始時のスタイル	starting:opacity-0	入場アニメーション向けの @starting-style バリアント
マスク	mask-*	画像／グラデーションのマスク用 CSS ユーティリティ
フィールドサイズ	field-sizing-content	テキストエリアと入力欄のサイズを自動調整します
インセットシャドウ	inset-shadow-*、inset-ring-*	内側のシャドウとリングのユーティリティ
ユーザーによる検証	user-valid:、user-invalid:	ユーザー操作後のフォーム検証
ポインタークエリー	pointer-fine:、pointer-coarse:	入力デバイスの精度を対象にします
不活性	inert:opacity-50	不活性な要素のスタイルを設定します
論理的なスペーシング	pbs-*、pbe-*、mbs-*、mbe-*	ブロック方向のパディング／マージン（v4.2）
論理的なサイズ	inline-*、block-*、min-inline-*、max-block-*	論理的な幅／高さのユーティリティ（v4.2）
論理的なインセット	inset-s-*、inset-e-*、inset-bs-*、inset-be-*	論理的な配置。start-*／end-* を置き換えます
論理的なボーダー	border-bs-*、border-be-*	ブロック方向のボーダーユーティリティ（v4.2）
フォント機能	font-features-['smcp']	OpenType の font-feature-settings（v4.2）
新しいカラーパレット	mauve、olive、mist、taupe	ニュートラルカラーのパレットを追加します（v4.2）
Webpack 統合	@tailwindcss/webpack	Tailwind を webpack プラグインとして実行します（v4.2）
色空間	OKLCH	v4 のデフォルトです。sRGB フォールバックが生成されます

よくある間違い

間違い	正しいパターン
v4 で tailwind.config.js を使用する	CSS 内の @theme { ... } で設定する
hsl(var(--background)) で二重にラップする	直接参照する：var(--background)
@layer base 内に :root／.dark を置く	@layer の外側のルートレベルで定義する
@layer components クラスで @apply を使う	カスタムユーティリティには @utility ディレクティブを使う
複数テーマの切り替えに @theme inline を使う	動的なテーマには inline なしで @theme を使う
あらゆる場所で bg-blue-500 のような生の色を使う	自動的に適応するセマンティックトークン（bg-primary）を使う
プラグインに require() または @import を使う	@plugin "package-name"; を使う
v4 で tailwindcss-animate を使う	代わりに tw-animate-css を使う
shadcn/ui で @theme inline がない	すべての CSS 変数を @theme inline ブロックにマッピングする
CSS で theme('colors.brand') を使う	ネイティブ CSS 変数の var(--color-brand) を使う
非推奨の start-*／end-* インセットを使う	論理ユーティリティの inset-s-*／inset-e-* を使う

委任

• クラスパターンの調査と使用例：Explore エージェントを使います
• 複数ファイルにわたる v3 から v4 への移行：Task エージェントを使います
• デザイントークンの階層とテーマ設定のアーキテクチャ：Plan エージェントを使います

motion スキルが利用可能な場合は、複雑なアニメーションパターン（スプリング物理、ジェスチャー、スクロール連動）を委任します。

参考資料

• 設定 -- CSS ファーストの設定、@theme、@theme inline、@utility、@plugin、@source、@reference、@variant ディレクティブ
• デザイントークン -- OKLCH トークンシステム、ブランドスケール、セマンティックトークン、シャドウ、z-index、流動的なタイポグラフィ
• コンポーネントパターン -- レイアウト、グリッド、コンテナクエリ、3D 変換、サブグリッド、CVA バリアント
• UI パターン -- バリアント、状態、アクセシビリティを備えたボタン、フォーム、ナビゲーション、カード、タイポグラフィ
• ダークモード -- クラスベースのダークモード、複数テーマのシステム、ThemeProvider、@custom-variant
• shadcn/ui との統合 -- 4 ステップのアーキテクチャ、components.json、tw-animate-css、Vite のセットアップ
• 移行 -- v3 から v4 への移行手順、破壊的変更、アップグレードツール、よくある落とし穴
• トラブルシューティング -- よくあるエラー、ビルドの修正、CSS レイヤーの問題、PostCSS の問題