2026年5月20日

WordPressでCSSカスタムプロパティ（CSS変数）を使う方法｜theme.jsonとの関係

テーマ・デザイン

CSS カスタムプロパティ（CSS 変数）は、--color-primary: #2271b1; のように名前を付けた値を定義し、var(--color-primary) で参照する CSS の仕組みです。色や余白を1か所で決めておけば、変えるときもその1か所を直すだけで済みます。

WordPress では、自分で定義する変数のほかに、テーマの theme.json に書いた色や文字サイズから WordPress が自動で作る変数（--wp--preset--…）も使えます。この記事では両方の使い方と、カスタマイザーや JavaScript との組み合わせ方を説明します。theme.json の仕様は、2026年10月時点の WordPress 開発者向けドキュメント（theme.json バージョン3）で確認しています。

基本: :rootで定義してvar()で参照する

子テーマの style.css か、「外観」→「カスタマイズ」→「追加 CSS」に書きます（ブロックテーマでは、サイトエディターの「スタイル」から開ける「追加 CSS」）。

:root {
	/* 色 */
	--color-primary: #2271b1;
	--color-primary-dark: #135e96;
	--color-text: #1d2327;
	--color-bg-alt: #f0f0f1;

	/* 余白 */
	--space-sm: 1rem;
	--space-md: 1.5rem;

	/* 角の丸み */
	--radius: 4px;
}

.site-header {
	background: var(--color-primary);
	padding: var(--space-sm) var(--space-md);
}

.notice-box {
	background: var(--color-bg-alt);
	border-left: 4px solid var(--color-primary);
	border-radius: var(--radius);
	/* 2つ目の値は、変数が定義されていないときに使われる */
	color: var(--color-note, var(--color-text));
}

:root は HTML 全体（<html> 要素）を指します。ここで定義した変数は、ページのどこからでも参照できます。
変数は子の要素に引き継がれます。.dark-section { --color-text: #fff; } のように、一部の範囲だけ値を変えることもできます。
名前は -- で始め、大文字と小文字は区別されます。
現在の主要なブラウザーはすべて対応しています。Internet Explorer は対応していませんが、WordPress も 5.8 で Internet Explorer 11 のサポートを終えています。

theme.jsonのプリセットから作られる変数

theme.json の settings に色・文字サイズ・余白のプリセット（エディターで選べる候補）を書くと、WordPress はそれぞれに対応する CSS 変数を作り、ページに出力します。プリセットの名前（name）はエディターに表示され、slug が変数名の一部になります。

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "slug": "primary", "color": "#2271b1", "name": "Primary" },
				{ "slug": "accent", "color": "#d63638", "name": "Accent" }
			]
		},
		"typography": {
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "large", "size": "1.5rem", "name": "Large" }
			]
		},
		"spacing": {
			"spacingSizes": [
				{ "slug": "40", "size": "1rem", "name": "Medium" },
				{ "slug": "60", "size": "2.5rem", "name": "Large" }
			]
		}
	}
}

この設定から作られる変数は次のとおりです。

設定	作られる変数	例
`color.palette`	`--wp--preset--color--{slug}`	`--wp--preset--color--primary`
`typography.fontSizes`	`--wp--preset--font-size--{slug}`	`--wp--preset--font-size--large`
`spacing.spacingSizes`	`--wp--preset--spacing--{slug}`	`--wp--preset--spacing--40`

色のプリセットからは、変数に加えて .has-primary-color（文字色）や .has-primary-background-color（背景色）のようなクラスも作られます。エディターで色を選ぶと、ブロックにこのクラスが付きます。文字サイズからは .has-large-font-size のようなクラスが作られます。

テーマの CSS からは、これらの変数をそのまま参照できます。

.site-header {
	background: var(--wp--preset--color--primary);
	padding: var(--wp--preset--spacing--40);
}

.site-title {
	font-size: var(--wp--preset--font-size--large);
}

色の値は theme.json で変えます。CSS で --wp--preset--color--primary を直接上書きすると、エディターで選べる色とページの色が食い違います。
自分で決めた名前を使いたい場合は、:root { --color-primary: var(--wp--preset--color--primary); } のように、プリセットの変数を参照する形にすると、値を theme.json の1か所で管理できます。
WordPress が用意している既定の文字サイズや余白のプリセットも、--wp--preset--… の変数として出力されます。既定のプリセットを使わない場合は、typography.defaultFontSizes や spacing.defaultSpacingSizes を false にします。

theme.jsonのcustomで独自の変数を作る

プリセットに当たらない値（行の高さ、角の丸みなど）は、settings.custom に書くと変数として出力されます。

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"custom": {
			"lineHeight": {
				"body": "1.8",
				"heading": "1.3"
			},
			"radius": "4px"
		}
	}
}

作られる変数は次のとおりです。

--wp--custom--line-height--body: 1.8;
--wp--custom--line-height--heading: 1.3;
--wp--custom--radius: 4px;

キーは --wp--custom-- の後ろに、入れ子ごとに -- でつながれます。lineHeight のような大文字を含む名前は、line-height のようにハイフンでつないだ小文字に変わります。

カスタマイザーで選んだ色を変数にする

クラシックテーマで、「外観」→「カスタマイズ」の色の設定から主な色を変えられるようにし、その値を CSS 変数として出力する例です。子テーマの functions.php に追加します。

<?php
add_action( 'customize_register', function ( WP_Customize_Manager $wp_customize ): void {
	$wp_customize->add_setting( 'wpdr_primary_color', array(
		'default'           => '#2271b1',
		'sanitize_callback' => 'sanitize_hex_color',
		'transport'         => 'refresh',
	) );

	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'wpdr_primary_color', array(
		'label'   => 'メインの色',
		'section' => 'colors',
	) ) );
} );

add_action( 'wp_head', function (): void {
	$color = sanitize_hex_color( get_theme_mod( 'wpdr_primary_color', '#2271b1' ) );
	if ( ! $color ) {
		return;
	}
	printf( '<style id="wpdr-custom-properties">:root { --color-primary: %s; }</style>' . "\n", esc_html( $color ) );
} );

colors は WordPress が用意しているカスタマイザーの「色」セクションの ID です。
sanitize_hex_color は、#2271b1 のような16進数の色だけを通し、それ以外は空にします。出力の前にも同じ関数を通しているので、不正な値が CSS に入りません。
テーマの CSS が var(--color-primary) を参照していれば、カスタマイザーで色を変えるだけでサイト全体の色が変わります。
'transport' => 'refresh' は、色を変えるたびにプレビューを読み込み直す設定です。読み込み直さずに即座に反映させる 'postMessage' にする場合は、プレビュー側で値を受け取る JavaScript も必要です。
ブロックテーマでは、「外観」に「カスタマイズ」が通常は表示されません。ブロックテーマでは、theme.json のプリセットと、サイトエディターの「スタイル」で色を変えます。

JavaScriptから読み書きする

CSS 変数は JavaScript から読み書きできます。ダークモードの切り替えなどに使えます。

const root = document.documentElement;

// 現在の値を読む（前後の空白を除く）
const primary = getComputedStyle( root ).getPropertyValue( '--color-primary' ).trim();
console.log( primary ); // 例: "#2271b1"

// 値を変える（<html> 要素の style 属性に書き込まれる）
root.style.setProperty( '--color-primary', '#d63638' );

// まとめて変える
const darkTheme = {
	'--color-text': '#f0f0f1',
	'--color-bg-alt': '#1d2327',
};
Object.entries( darkTheme ).forEach( function ( [ name, value ] ) {
	root.style.setProperty( name, value );
} );

// 元に戻す（style 属性から取り除くと、CSS の値に戻る）
root.style.removeProperty( '--color-primary' );

setProperty() で書き込んだ値は <html> 要素の style 属性に入るため、:root に書いた CSS の値より優先されます。ページを移動すると消えるので、切り替えを覚えておく場合は localStorage などに保存し、次のページで読み込み直す処理が必要です。

まとめ

CSS 変数は :root で --名前: 値; と定義し、var(--名前) で参照する。var() の2つ目の値は、変数が無いときの代わりの値になる。
theme.json のプリセットからは --wp--preset--color--{slug}・--wp--preset--font-size--{slug}・--wp--preset--spacing--{slug} が、settings.custom からは --wp--custom--… が作られる。プリセットの値は theme.json で変え、CSS で直接上書きしない。
クラシックテーマでは、カスタマイザーの値を wp_head で :root の変数として出力すると、CSS を変えずに色を切り替えられる。
JavaScript では getComputedStyle().getPropertyValue() で読み、style.setProperty() で書き換える。