---

name: migrating-tailwindcss-v4 description: Tailwind CSS v4 移行ルール。v3からv4への構文変更を自動修正。aria/data属性の短縮形、変数構文、shorthandクラス、important位置、競合クラスの解決パターンを提供。「Tailwind v4 移行」「Tailwind 最新構文」「cssConflict 修正」時に使用。

Tailwind CSS v4 移行ガイド

ESLint プラグイン設定

eslint-plugin-better-tailwindcss を使用してCLIで検出・自動修正する。

Copypnpm add -D eslint-plugin-better-tailwindcss

Copy// eslint.config.mjs
import betterTailwindcss from 'eslint-plugin-better-tailwindcss';

export default [
  {
    plugins: {
      'better-tailwindcss': betterTailwindcss,
    },
    settings: {
      'better-tailwindcss': {
        entryPoint: 'src/app/globals.css', // Tailwind v4 CSS設定ファイル
      },
    },
    rules: {
      'better-tailwindcss/enforce-consistent-class-order': 'warn',
      'better-tailwindcss/enforce-consistent-important-position': 'warn',
      'better-tailwindcss/enforce-consistent-line-wrapping': 'warn',
      'better-tailwindcss/enforce-consistent-variable-syntax': 'warn',
      'better-tailwindcss/enforce-shorthand-classes': 'warn',
      'better-tailwindcss/no-duplicate-classes': 'warn',
      'better-tailwindcss/no-unnecessary-whitespace': 'warn',
      'better-tailwindcss/no-conflicting-classes': 'error',
      'better-tailwindcss/no-unregistered-classes': 'off', // カスタムテーマ使用時はoff
    },
  },
];

自動修正: npx eslint . --fix

手動修正パターン

ESLint プラグインが未対応のパターンは sed で一括置換する。

ARIA 属性の短縮形

Copy# aria-[invalid=true] → aria-invalid
find src -name "*.tsx" -exec sed -i '' 's/aria-\[invalid=true\]/aria-invalid/g' {} \;

# aria-[selected=true] → aria-selected
find src -name "*.tsx" -exec sed -i '' 's/aria-\[selected=true\]/aria-selected/g' {} \;

# aria-[current=true] → aria-current
find src -name "*.tsx" -exec sed -i '' 's/aria-\[current=true\]/aria-current/g' {} \;

# aria-[disabled=true] → aria-disabled
find src -name "*.tsx" -exec sed -i '' 's/aria-\[disabled=true\]/aria-disabled/g' {} \;

Data 属性の短縮形

Copy# data-[x] → data-x (存在チェックのみの場合)
find src -name "*.tsx" -exec sed -i '' 's/data-\[\([a-z-]*\)\]/data-\1/g' {} \;

CSS プロパティからユーティリティへ

Copy# [grid-template-rows:auto] → grid-rows-[auto]
find src -name "*.tsx" -exec sed -i '' 's/\[grid-template-rows:auto\]/grid-rows-[auto]/g' {} \;

ピクセル値の短縮形

分数値の短縮形

競合クラスの解決

outline と outline-N を同時に使用すると競合が発生する。

問題

Copy// NG: outline は style + width を設定、outline-4 は width のみ
className="focus:outline focus:outline-4"

解決策

Copy// OK: outline-solid は style のみ設定
className="focus:outline-solid focus:outline-4"

一括修正

Copyfind src -name "*.tsx" -exec sed -i '' 's/focus:outline focus:outline-/focus:outline-solid focus:outline-/g' {} \;
find src -name "*.tsx" -exec sed -i '' 's/focus-visible:outline focus-visible:outline-/focus-visible:outline-solid focus-visible:outline-/g' {} \;
find src -name "*.tsx" -exec sed -i '' 's/hover:outline hover:outline-/hover:outline-solid hover:outline-/g' {} \;
find src -name "*.tsx" -exec sed -i '' 's/outline outline-\([0-9]\)/outline-solid outline-\1/g' {} \;

v4 新構文まとめ