Tailwind CSS カスタムカラー設定ガイド（v3 / v4 対応・CSS変数・透過指定）

Tailwind CSS において、ブランドカラーや独自デザインシステムのカラーパレットを追加・カスタマイズする手順、および bg-brand/50 などの透過モディファイアを正常に機能させる設定方法です。

1. オンライン Tailwind カラーコード変換ツール

HEX カラーコードから Tailwind 互換のカラーネームとクラス名をブラウザ内で相互生成・プレビューできます。

---

2. Tailwind v3 での設定 (tailwind.config.ts)

既存の標準カラー（slate, blue 等）を消さずに独自カラーを追加する場合は、必ず theme.extend.colors 内に記述します（※ theme.colors 直下に書くと標準色がすべて上書き消去されます）。

// tailwind.config.ts
import type { Config } from 'tailwindcss';

const config: Config = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          500: '#0284c7', // bg-brand-500 または bg-brand (DEFAULT設定時)
          DEFAULT: '#0284c7', // bg-brand として使える
          900: '#0c4a6e',
        },
        accent: '#f59e0b', // bg-accent
      },
    },
  },
};

export default config;

---

3. Tailwind v4 での最新設定 (@theme ディレクティブ)

Tailwind v4 では tailwind.config.js が廃止され、CSS ファイル内の @theme ディレクティブでカラー変数を定義します。

/* main.css (Tailwind v4) */
@import "tailwindcss";

@theme {
  --color-brand-500: #0284c7;
  --color-brand-default: #0284c7;
  --color-accent: #f59e0b;
}

これで bg-brand-500 や text-accent が自動生成されます。

---

4. Dynamic CSS 変数 ＋ 透過モディファイア (bg-brand/50) の連携

ダークモード切り替えやテーマ変更で CSS 変数を使う場合、bg-brand/50（透明度 50%）を機能させるには RGB 値のみ（カンマ区切りなし）を CSS 変数に格納 します。

/* CSS 変数側 (RGB値のみ定義) */
:root {
  --color-primary-rgb: 2, 132, 199;
}

// tailwind.config.ts で <alpha-value> プレースホルダーを接続
colors: {
  primary: 'rgb(var(--color-primary-rgb) / <alpha-value>)',
}

これで bg-primary/50 や text-primary/80 が透過属性を維持したまま正常に動作します。