tailwind-best-practices

使用する場面

Tailwind CSS コードを扱うときに、このスキルを使用します。AI エージェントは Tailwind v3 のデータでトレーニングされているため、誤った設定ファイル、非推奨のディレクティブ、削除済みのユーティリティ、冗長なクラスリストなど、古いパターンを一貫して生成します。このスキルでは、Tailwind CSS v4 のパターンを徹底します。

重要なルール

1. @tailwind ディレクティブの代わりに CSS の @import を使用する

誤り（エージェントがよく使うパターン）：

@tailwind base;
@tailwind components;
@tailwind utilities;

正しい例：

@import "tailwindcss";

理由： Tailwind v4 では @tailwind ディレクティブが完全に削除されました。標準的な CSS の @import 文を使用してください。

2. @theme を使った CSS ファーストの設定を使用する

誤り（エージェントがよく使うパターン）：

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
      },
      spacing: {
        18: "4.5rem",
      },
    },
  },
};

正しい例：

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --spacing-18: 4.5rem;
}

理由： Tailwind v4 では、@theme ディレクティブを使った CSS ファーストの設定を使用します。ほとんどのプロジェクトでは tailwind.config.js は必要ありません。

3. @tailwindcss/postcss プラグインを使用する

誤り（エージェントがよく使うパターン）：

// postcss.config.mjs
export default {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

正しい例：

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

理由： v4 では、postcss-import と autoprefixer は自動的に処理されます。プラグインは tailwindcss ではなく、@tailwindcss/postcss です。

4. モダンな不透明度の構文を使用する

誤り（エージェントがよく使うパターン）：

<div class="bg-red-500 bg-opacity-50">
  <div class="text-blue-600 text-opacity-75"></div>
</div>

正しい例：

<div class="bg-red-500/50">
  <div class="text-blue-600/75"></div>
</div>

理由： bg-opacity-*、text-opacity-*、border-opacity-*、placeholder-opacity-* ユーティリティは v4 で削除されました。スラッシュ修飾子の構文を使用してください。

5. カスタムカラーには CSS 変数を使用する

誤り（エージェントがよく使うパターン）：

<div class="bg-[#3b82f6]"></div>

正しい例：

@theme {
  --color-brand: #3b82f6;
}

<div class="bg-brand"></div>

理由： 任意の値（bg-[#3b82f6]）は、できるだけ使用しないようにします。カスタムカラーを @theme で定義すると、 再利用でき、一貫性を保てます。

6. @container を使ってコンテナークエリを使用する

誤り（エージェントがよく使うパターン）：

<div class="md:flex-row flex-col"></div>

正しい例（ビューポートではなく親要素のサイズに基づいてサイズを決める場合）：

<div class="@container">
  <div class="flex flex-col @md:flex-row">
    
  </div>
</div>

理由： Tailwind v4 にはコンテナークエリのサポートが組み込まれています。親要素に @container を使い、 子要素に @sm:、@md:、@lg: バリアントを使うことで、コンポーネント単位のレスポンシブデザインを実現できます。

7. カスタムユーティリティには @utility を使用する

誤り（エージェントがよく使うパターン）：

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

正しい例：

@utility content-auto {
  content-visibility: auto;
}

理由： Tailwind v4 では、カスタムユーティリティに @layer utilities ではなく @utility ディレクティブを使用します。

8. 正しい important 修飾子を使用する

誤り（エージェントがよく使うパターン）：

// tailwind.config.js
module.exports = {
  important: true,
};

正しい例：

@import "tailwindcss" important;

理由： v4 では important オプションの場所が設定ファイルから CSS の import 文に移動しました。

9. 名前が変更されたユーティリティを使用する

誤り（エージェントがよく使うパターン）：

<div class="shadow-sm ring-1 ring-gray-900/5">
  <div class="blur-sm">
    <div class="rounded-sm"></div>
  </div>
</div>

正しい例：

<div class="shadow-xs ring-1 ring-gray-900/5">
  <div class="blur-xs">
    <div class="rounded-xs"></div>
  </div>
</div>

理由： v4 では、shadow-sm は shadow-xs に、shadow は shadow-sm に、blur-sm は blur-xs に、rounded-sm は rounded-xs に変更されたほか、同様の変更が行われています。以前の -sm の値は、 以前のデフォルト値に対応するようになりました。

10. モダンなグラデーション構文を使用する

誤り（エージェントがよく使うパターン）：

<div class="bg-gradient-to-r from-blue-500 to-purple-500"></div>

正しい例：

<div class="bg-linear-to-r from-blue-500 to-purple-500"></div>

理由： Tailwind v4 では bg-gradient-to-* が bg-linear-to-* に変更され、bg-conic-* や bg-radial-* など、ほかの種類のグラデーションもサポートされました。

11. 否定には not-* バリアントを使用する

誤り（エージェントがよく使うパターン）：

<div class="hover:bg-blue-500">
  
</div>

正しい例：

<div class="not-hover:opacity-75 hover:opacity-100"></div>

理由： Tailwind v4 では、条件に一致しない要素にスタイルを適用するための not-* バリアントが追加されました。

12. 表示時のアニメーションには @starting-style を使用する

誤り（エージェントがよく使うパターン）：

.modal {
  opacity: 0;
  transition: opacity 0.3s;
}
.modal.open {
  opacity: 1;
}

正しい例：

<div class="starting:opacity-0 opacity-100 transition-opacity duration-300"></div>

理由： Tailwind v4 では starting: バリアントを通じて @starting-style をサポートしており、JavaScript を使わずに CSS のみで表示時のアニメーションを実現できます。

パターン

• カスタムデザイントークンはすべて @theme ブロックで定義する
• エントリーポイントには @import "tailwindcss" のみを使用する
• コンポーネント単位のレスポンシブデザインにはコンテナークエリ（@container + @md:）を使用する
• 不透明度にはスラッシュ修飾子を使用する：bg-blue-500/50、text-gray-900/75
• カスタムユーティリティには @utility、カスタムバリアントには @variant を使用する
• グラデーションには bg-linear-to-* を使用する（bg-gradient-to-* は使用しない）

アンチパターン

• JavaScript ベースの動的設定が必要でない限り、tailwind.config.js は作成しないでください
• @tailwind base/components/utilities は使用せず、@import "tailwindcss" を使用してください
• bg-opacity-*、text-opacity-* は使用せず、スラッシュ修飾子の構文を使用してください
• カスタムユーティリティに @layer utilities は使用せず、@utility を使用してください
• bg-gradient-to-* は使用せず、bg-linear-to-* を使用してください
• v4 では組み込みのため、postcss-import や autoprefixer は使用しないでください
• 最小の影を指定する場合は shadow-sm を使用しないでください。現在は shadow-xs です