CSSカスタムプロパティでテーマ値を管理する設計

CSSカスタムプロパティは、色・余白・角丸・文字サイズのような繰り返し使う値を、スタイルシート全体で共有するための仕組みです。値を一か所に集めるだけではありません。見た目そのものではなく、その値が担う役割を名前にすることで、テーマ変更やコンポーネント追加で起きる値のばらつきを抑えられます。

役割ごとのテーマ値をrootで定義し、コンポーネントがvarで参照し、テーマのスコープで値だけを上書きする流れ

まず役割ごとの値を定義する

ページ全体で使う値は :rootに置きます。--blue-500のような色名だけの変数と、--color-linkのような役割の変数を混ぜると、使う側が判断しにくくなります。小規模なサイトでは、まず役割の変数から始めると運用しやすくなります。

:root {
  --color-text: #1f2937;
  --color-surface: #ffffff;
  --color-link: #0f83d8;
  --space-4: 1rem;
  --radius-card: 0.75rem;
}

.card {
  color: var(--color-text);
  background: var(--color-surface);
  padding: var(--space-4);
  border-radius: var(--radius-card);
}

コンポーネント側では具体的なカラーコードやピクセル値を直接書かず、var(--color-text)のように参照します。こうしておけば、リンク色やカードの余白を変更する際に、同じ値を探して複数ファイルを修正する必要がありません。

値の階層を増やしすぎない

カスタムプロパティは再定義できるため、設計を複雑にしすぎると「実際に使われる値」が追えなくなります。--color-linkが--brand-primaryを参照し、さらに別の変数を参照するような多段構造は、テーマを複数持つ必要が出てから検討します。

最初は、次のように三つの種類に絞ると見通しを保てます。

色: テキスト、背景、境界線、リンク、強調
間隔: 余白や要素間のすき間に使う段階的な値
形と文字: 角丸、影、本文・見出しの文字サイズ

値が一度しか使われない場合や、特定の要素だけに意味がある計算値まで共通化する必要はありません。変数を増やすことより、変更時にどこを直せばよいか分かることを優先します。

テーマ切り替えは参照先だけ変える

同じ変数は、必要な範囲で再定義できます。たとえばdata-theme属性のある要素で色の値だけを上書きすれば、カードなどのコンポーネントを変更せずにテーマを切り替えられます。

[data-theme="dark"] {
  --color-text: #e5e7eb;
  --color-surface: #111827;
  --color-link: #7dd3fc;
}

ここで--color-textのような役割名を使う意味が出ます。ダークテーマで実際の色が変わっても、コンポーネントは「本文の文字色を使う」という意味のままです。テーマごとに.card-darkのような派生クラスを増やすより、共通コンポーネントを保ちやすくなります。

フォールバックとスコープを理解する

変数が定義されていない可能性がある箇所では、var()の第二引数にフォールバックを指定できます。

.notice {
  border-left: 4px solid var(--color-notice, #0f83d8);
}

ただし、基本となるテーマ値に毎回フォールバックを付けると、定義漏れを見つけにくくなります。意図的に任意設定にした値だけに使う方が適切です。また、カスタムプロパティは要素から子要素へ継承されます。コンポーネントの内側で再定義すると、その子孫にも影響するため、ページ全体の値は :root、局所的な変更は対象コンポーネントのルート要素に限定します。

命名と確認の基準をそろえる

命名規則は、厳密な形式より一貫性が重要です。--color-*、--space-*、--radius-*のように接頭辞をそろえ、値を追加するときは「二か所以上で使うか」「役割を説明できるか」を確認します。テーマを変えた後は、文字と背景の組み合わせ、リンクの視認性、フォーカス表示まで確認してください。

カスタムプロパティはCSSを短くするためだけの機能ではありません。変更に強い共通語彙をスタイルシートに作るための道具です。少数の役割ベースの値から始め、実際に繰り返しが見えたものだけを追加すると、過剰な抽象化を避けながらテーマ管理を育てられます。

一方で、すべての値を変数にする必要はありません。一度しか使わない値や、要素固有の計算値まで共通化すると、参照元を追いにくくなります。まずは色、余白、角丸、文字サイズなど、複数箇所で繰り返されるテーマ値に限定します。命名規則と定義場所をそろえることで、変更範囲を小さく保てます。

CSSのモダンレイアウト