---
title: Tailwind CSS
description: Tailwind CSS v4 の導入方法、テーマ変数、@apply、BEM との併用方針
---

## 導入方法

Tailwind CSS v4 は、ビルド時に CSS を生成する方法で導入します。導入手順は、テンプレートの README（Astro テンプレート・WordPress テンプレート）か、[Tailwind CSS の公式ドキュメント](https://tailwindcss.com/docs/installation)を参照してください。

v4 では `tailwind.config.js` は不要です。CSS ファイル内の `@theme` ディレクティブでテーマを定義します。

:::danger[本番環境での Play CDN 利用禁止]
Play CDN（`@tailwindcss/browser`）は開発・プロトタイプ用です。本番環境では、ビルドした CSS ファイルを使用してください。
:::

## クラスの並び順

Tailwind CSS のクラスは公式の推奨順序で記述します。  
Prettier を使うプロジェクトでは、[Prettier Plugin for Tailwind CSS](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) を導入して自動で並べ替えてください。

## テーマ変数

### @theme ディレクティブ

プロジェクト全体で一貫して使用する値は、`@theme` ディレクティブでテーマ変数として定義します。  
定義した変数は、名前空間（`--color-*`、`--spacing-*`、`--font-*` など）に対応したユーティリティクラスとして利用可能になります。

```css
@import "tailwindcss";

@theme {
  /* カラー */
  --color-primary: #0070f3;
  --color-secondary: #555;
  --color-bg: #fff;

  /* スペーシング */
  --spacing-sm: 0.5rem;
  --spacing-md: 1.5rem;
  --spacing-lg: 2rem;

  /* フォント */
  --font-sans: "Helvetica Neue", Arial, sans-serif;
}
```

```html
<!-- テーマ変数から生成されたユーティリティクラスを使用 -->
<div class="bg-primary p-md font-sans text-white">コンテンツ</div>
```

### カスタムプロパティとの統合

`@theme` で定義した変数のうち、ユーティリティクラスなどで使われたものはカスタムプロパティとして `:root` にも出力されます（すべて出力する場合は `@theme static` を使用します）。  
既存の[カスタムプロパティ](/frontend/css/variables)を参照してテーマ変数を定義する場合は、`@theme inline` を使用してください。  
`inline` を付けると、ユーティリティクラスが参照先の変数を直接使うため、テーマ切り替えなどで値を上書きしても正しく反映されます。

```css
@import "tailwindcss";

/* 既存のカスタムプロパティ */
:root {
  --brand-primary: #0070f3;
  --brand-bg: #fff;
}

/* ダークテーマ */
:root[data-theme="dark"] {
  --brand-primary: #66bee7;
  --brand-bg: #222;
}

/* テーマ変数として参照 */
@theme inline {
  --color-primary: var(--brand-primary);
  --color-bg: var(--brand-bg);
}
```

```html
<div class="bg-bg text-primary">コンテンツ</div>
```

:::warning
`@theme { --color-primary: var(--color-primary); }` のように同じ名前の変数を参照すると循環参照になり、値が無効になります。参照元とテーマ変数は別の名前にしてください。
:::

`data-theme` 属性で `dark:` バリアントを切り替える場合は、`@custom-variant` で `dark` バリアントを上書きします。

```css
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

## @apply ディレクティブ

`@apply` ディレクティブは、繰り返し使用されるユーティリティクラスの組み合わせをコンポーネントクラスに抽出する場合に使用します。

```css
/* ✅ 良い例：繰り返し使用されるパターンを @apply で抽出 */
.button {
  @apply rounded px-4 py-2 font-medium;
}

.button--primary {
  @apply bg-primary text-white;
}
```

ただし、`@apply` の多用は避け、次の場合にのみ使用してください。

- フレームワークなどでコンポーネント化できない場合（WordPress など）
- 同じユーティリティクラスの組み合わせを、複数のテンプレートで使い回す場合

:::note
Vue・Svelte の `<style>` ブロックや CSS Modules など、メインの CSS とは別に処理されるファイルで `@apply` やテーマ変数を使う場合は、`@reference "../app.css";` のようにメインの CSS を参照してください。
:::

## 任意値（Arbitrary values）の使用を控える

`text-[16px]` のような任意値はなるべく使わないでください。  
繰り返し使う値は `@theme` でテーマ変数として定義し、標準またはテーマ由来のユーティリティクラスを使います。

```html
<!-- ❌ 悪い例：任意値を多用 -->
<div class="text-[#0070f3] text-[16px]">コンテンツ</div>

<!-- ✅ 良い例：テーマ変数や標準のユーティリティクラスを使用 -->
<div class="text-base text-primary">コンテンツ</div>
```

## BEM との併用

Tailwind CSS を使用する場合も、次のように役割を分けます。

- **コンポーネントのスタイル**: 再利用するコンポーネントは [BEM 記法](/frontend/css/naming)のクラスを付け、CSS に書きます。
- **ページ固有の配置・余白**: コンポーネントの外側の配置や余白の調整に、ユーティリティクラスを使います。
- **複雑なアニメーション**: 複数のキーフレームや複雑なトランジションが必要な場合は、ユーティリティクラスではなく CSS に書きます。

同じ要素に BEM のクラスと、色や文字サイズなど見た目を変えるユーティリティクラスを混在させないでください。スタイルの定義場所が 2 か所に分かれ、変更時に見落としやすくなります。

```html
<!-- ✅ 良い例：配置の調整だけをユーティリティクラスで行う -->
<div class="card mt-8">...</div>

<!-- ❌ 悪い例：BEM のクラスの見た目をユーティリティクラスで上書きする -->
<div class="card bg-primary text-lg">...</div>
```
