---
title: カスタムプロパティ
description: カスタムプロパティの定義・命名・スコープ・テーマ切り替え
---

カスタムプロパティ（CSS 変数）は、再利用性・保守性・テーマ切り替え（ダークモードなど）の柔軟性向上のため積極的に活用します。プロジェクトの規模や要件に応じて、粒度や管理方法は調整してください。

## 定義

色・余白・フォントサイズ・`z-index` など、プロジェクト全体で共通化したい値を中心に利用します。

```css
:root {
  --color-bg: #fff;
  --color-text: #222;
  --spacing-sm: 0.5rem;
  --text-lg: 1.25rem;
  --z-index-header: 100;
}

.header {
  z-index: var(--z-index-header);
  padding: var(--spacing-sm) 0;
  font-size: var(--text-lg);
  color: var(--color-text);
  background: var(--color-bg);
}
```

## 命名

カスタムプロパティには、用途・意味が明確な英語名（ケバブケース）を付けます。

用途ごとに次の接頭辞を使います。

```css
/* ✅ 良い例 */
:root {
  --color-primary: #0070f3;
  --color-secondary: #555;
  --color-bg: #fff;
  --text-base: 1rem;
  --spacing-md: 1.5rem;
  --radius-md: 4px;
}

/* ❌ 悪い例 */
:root {
  --a: #0070f3;
  --b1: 2rem;
  --maincolor: #0070f3;
  --secondaryColor: #00f365;
}
```

## スコープ

グローバルに使うカスタムプロパティは `:root` で定義し、コンポーネント固有のものはそのスコープ内で定義します。

```css
:root {
  --color-primary: #0070f3;
  --spacing-md: 1.5rem;
}

.button {
  padding: var(--spacing-md);
  background: var(--color-primary);
}

/* 特定の要素だけ値を上書きする場合は、スコープ内で再定義する */
.header--light {
  --color-primary: #fff;
}

.header--light .button {
  background: var(--color-primary); /* 白色になる */
}
```

## テーマ切り替え

ダークモードに対応する場合は、`color-scheme` を宣言し、既定では OS の設定（`prefers-color-scheme`）に追従させます。`light-dark()` を使うと、ライト・ダークの値を 1 か所にまとめて書けます。

```css
:root {
  color-scheme: light dark;
  --color-bg: light-dark(#fff, #222);
  --color-text: light-dark(#222, #eee);
}
```

サイト上に手動の切り替えボタンを置く場合は、`data-theme` 属性で `color-scheme` を上書きします。`light-dark()` は `color-scheme` の値に応じて切り替わるため、カスタムプロパティを再定義する必要はありません。

```css
:root[data-theme="light"] {
  color-scheme: light;
}

:root[data-theme="dark"] {
  color-scheme: dark;
}
```

## Tailwind CSS との統合

Tailwind CSS を使用する場合は、`@theme inline` でカスタムプロパティをテーマ変数として参照できます。  
詳細は [Tailwind CSS](/frontend/css/tailwind#カスタムプロパティとの統合) を参照してください。
