【WordPress】theme.json の使い方｜settings と styles でテーマ全体のスタイルを管理する

テーマのカラーパレットは functions.php、エディターの制限はフィルター、スタイルは style.css……と、テーマの設定があちこちに散らばって管理しづらい。そんな状況を1つのファイルにまとめて解決してくれるのが theme.json です。この記事では、theme.json の基本的な仕組みから、settings によるエディターの制御とプリセットの定義、styles による要素・ブロック単位のスタイル指定、自動生成される CSS カスタムプロパティの使い方までを解説します。ブロックテーマやカスタムブロック開発に入門する方に向けた内容です。

theme.json とは — テーマ直下に置く1つの設定ファイル

theme.json は、WordPress 5.8 で導入されたテーマの設定ファイルです。テーマフォルダーの直下に theme.json という名前で置くだけで WordPress が自動的に読み込み、特別な登録処理は必要ありません。ブロックテーマでは事実上必須のファイルですが、従来のクラシックテーマに置いても有効に働きます。

このファイルで管理できるのは、大きく分けて2つです。1つは「エディターでユーザーに何を許可し、どんな選択肢（プリセット）を用意するか」という設定で、settings キーに書きます。もう1つは「サイト全体・要素・ブロックにどんなスタイルを当てるか」という指定で、styles キーに書きます。まずは最小構成を見てみましょう。

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#1e40af", "name": "プライマリー" },
        { "slug": "secondary", "color": "#0d9488", "name": "セカンダリー" }
      ]
    }
  }
}

version はスキーマのバージョンを表す必須のキーで、現在の最新は WordPress 6.6 以降で使える version 3 です。$schema は省略できますが、指定しておくと VS Code などのエディターでキー名の補完や構文チェックが効くようになるので、書いておくことをおすすめします。この例をテーマに置くだけで、ブロックエディターのカラーパレットに「プライマリー」「セカンダリー」の2色が追加されます。

settings — エディターの選択肢とプリセットを定義する

settings は「エディターの UI をどう見せるか」を決めるセクションです。色・文字サイズ・余白などのプリセットを定義すると、それがエディターの選択肢として表示され、同時に後述する CSS カスタムプロパティが自動生成されます。逆に、機能そのものを無効にしてユーザーの自由入力を制限することもできます。

color — パレットの定義とカラーピッカーの制限

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#1e40af", "name": "プライマリー" },
        { "slug": "secondary", "color": "#0d9488", "name": "セカンダリー" },
        { "slug": "base", "color": "#ffffff", "name": "ベース" },
        { "slug": "contrast", "color": "#1f2937", "name": "コントラスト" }
      ],
      "custom": false,
      "customGradient": false,
      "defaultPalette": false
    }
  }
}

palette の各項目は slug（識別子）・color（色の値）・name（エディターに表示される名前）の3つで構成します。slug はこのあと CSS カスタムプロパティやクラス名の一部になるので、半角英数のケバブケースで付けてください。

あわせて指定している custom: false は、ユーザーが任意の色を選べるカラーピッカーを非表示にする設定です。defaultPalette: false は WordPress 本体が用意している既定のパレットを非表示にします。この2つを組み合わせると「テーマが定義した色しか使えない」状態を作れるため、サイトの配色を崩されたくない案件で重宝します。

typography と spacing — 文字サイズ・余白のプリセット

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "小" },
        { "slug": "medium", "size": "1rem", "name": "中" },
        { "slug": "large", "size": "1.5rem", "name": "大" }
      ],
      "defaultFontSizes": false
    },
    "spacing": {
      "units": [ "px", "rem", "%" ],
      "spacingSizes": [
        { "slug": "40", "size": "1rem", "name": "S" },
        { "slug": "50", "size": "2rem", "name": "M" },
        { "slug": "60", "size": "4rem", "name": "L" }
      ],
      "defaultSpacingSizes": false
    }
  }
}

typography.fontSizes は文字サイズの選択肢、spacing.spacingSizes はパディングやマージンで選べる余白サイズの選択肢を定義します。spacing.units は余白の手入力で使える単位の制限です。defaultFontSizes と defaultSpacingSizes は version 3 で追加されたキーで、false にすると WordPress 既定のプリセットを非表示にして、テーマが定義したものだけを表示できます。

appearanceTools — 隠れている UI をまとめて有効化する

ボーダー・リンク色・行間・ブロック間隔（blockGap）など、一部のスタイル設定 UI は既定では無効になっています。settings の直下に "appearanceTools": true と書くと、これらをまとめて有効にできます。1つずつ border.width や typography.lineHeight を true にしていくこともできますが、ブロックテーマではまとめて有効にしてしまうのが手軽です。

blocks — 特定のブロックだけ設定を変える

settings に書いた内容はすべてのブロックに適用されますが、settings.blocks の下にブロック名をキーとして書くと、そのブロックだけ設定を上書きできます。たとえば「見出しブロックだけはカスタムカラーを禁止する」なら次のように書きます。

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "blocks": {
      "core/heading": {
        "color": {
          "custom": false
        }
      }
    }
  }
}

プリセットから自動生成される CSS カスタムプロパティ

settings でプリセットを定義すると、WordPress はそこから CSS カスタムプロパティ（CSS 変数）とユーティリティクラスを自動生成し、フロントとエディターの両方に出力します。命名規則は --wp--preset--種類--スラッグ です。主な対応は次のとおりです。

これらの変数はテーマの style.css やカスタムブロックの CSS から自由に参照できます。色の値そのものを CSS に直書きせず変数を経由しておけば、あとから theme.json の1か所を変えるだけでサイト全体に反映されます。

/* theme.json のパレットで定義した色を参照する */
.site-footer {
  background-color: var(--wp--preset--color--primary);
  padding: var(--wp--preset--spacing--50);
}

プリセットの枠に収まらない独自の値は、settings.custom に書けます。ここに書いた値は --wp--custom--キー名 という変数になり、ネストしたキーは -- でつながれ、キャメルケースはケバブケースに変換されます。たとえば "custom": { "contentGap": "2rem" } は --wp--custom--content-gap として出力されます。

styles — サイト全体・要素・ブロックにスタイルを当てる

styles は実際にスタイルを適用するセクションです。styles の直下に書いたものはサイト全体（body 相当）に、styles.elements に書いたものはリンクや見出しなどの要素に、styles.blocks に書いたものは特定のブロックに適用されます。書いた内容は WordPress がグローバルスタイルとして CSS に変換し、自動で出力してくれます。

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "styles": {
    "color": {
      "background": "var:preset|color|base",
      "text": "var:preset|color|contrast"
    },
    "typography": {
      "fontSize": "var:preset|font-size|medium",
      "lineHeight": "1.8"
    },
    "elements": {
      "link": {
        "color": { "text": "var:preset|color|primary" }
      },
      "h2": {
        "typography": { "fontSize": "1.75rem", "fontWeight": "700" }
      }
    },
    "blocks": {
      "core/quote": {
        "color": { "background": "#f3f4f6" },
        "spacing": {
          "padding": { "top": "var:preset|spacing|40", "bottom": "var:preset|spacing|40" }
        }
      }
    }
  }
}

値の中に出てくる var:preset|color|primary は、theme.json 独自のプリセット参照記法です。生成後の CSS では var(--wp--preset--color--primary) に展開されます。var(--wp--preset--color--primary) とそのまま書いても動作しますが、公式ドキュメントでは var: 記法が使われています。settings で定義したプリセットを styles から参照する、という流れが theme.json の基本形です。

elements に指定できるのは link・button・heading（見出し全体）・h1〜h6・caption・cite です。styles 直下 → elements → blocks の順に適用範囲が狭くなり、狭いほうの指定が優先されます。

block.json の supports との関係

カスタムブロックを開発している場合、block.json の supports と theme.json の settings がどう関係するのかを押さえておくと混乱しません。役割分担はシンプルで、supports は「このブロックは背景色や余白の設定に対応している」というブロック側の宣言、theme.json の settings は「その設定 UI にどんな選択肢を出すか（そもそも出すか）」というテーマ側の制御です。

たとえば block.json で "supports": { "color": { "background": true } } と宣言したブロックには背景色の設定パネルが表示され、その選択肢として theme.json の color.palette で定義したパレットが並びます。テーマ側が settings.blocks でそのブロックのカラー設定を無効化すれば、ブロックが対応していても UI は表示されません。両者が許可して初めて UI が使える、という関係です。また、カスタムブロックの CSS でテーマのプリセット変数（--wp--preset--color--primary など）を参照しておくと、どのテーマで使われてもテーマの配色に馴染むブロックを作れます。

add_theme_support からの置き換え

theme.json が登場する前は、エディターのカラーパレットや文字サイズは functions.php の add_theme_support() で登録していました。theme.json はこれらの多くを置き換えるもので、theme.json と add_theme_support() の両方で同じ設定をした場合は theme.json の内容が優先されます。主な対応関係は次のとおりです。

新しくテーマを作るなら、これらを functions.php に書く理由はもうありません。クラシックテーマを保守している場合も、theme.json を1枚追加して add_theme_support() の設定を段階的に移していくことができます。

theme.json の変更が反映されないときの確認ポイント

JSON の構文エラーで全体が無視されている

theme.json は純粋な JSON ファイルなので、末尾の余分なカンマ（trailing comma）やコメントの記入は構文エラーになります。構文が壊れているとエラー画面は出ず、ファイル全体が黙って無視されるため「書いたのに何も変わらない」という症状になります。$schema を指定したエディターで編集するか、JSON のバリデーターに通して構文を確認してください。

サイトエディターでの変更が theme.json を上書きしている

グローバルスタイルには優先順位があり、WordPress 本体の既定値 → 親テーマの theme.json → 子テーマの theme.json → サイトエディター（外観 > エディター）でユーザーが保存したスタイル、の順に後のものが勝ちます。サイトエディターで一度でもスタイルを変更して保存していると、その内容はデータベースに保存され、theme.json をいくら編集しても画面に反映されません。サイトエディターのスタイル画面にあるリセット機能でユーザー変更を破棄すると、theme.json の内容が見えるようになります。

version と WordPress のバージョンが合っていない

version: 3 のスキーマが使えるのは WordPress 6.6 以降です。defaultFontSizes のように version 3 で追加されたキーは、古い WordPress では動作しません。運用中のサイトの WordPress バージョンと、theme.json の version・使用しているキーが対応しているかを確認してください。

まとめ

theme.json は、テーマ直下に置くだけで有効になる設定ファイルで、settings でエディターの選択肢とプリセットを定義し、styles でサイト全体・要素・ブロックのスタイルを指定します。プリセットからは --wp--preset--color--{slug} などの CSS カスタムプロパティが自動生成され、style.css やカスタムブロックの CSS からも参照できます。

block.json の supports が「ブロックが何に対応するか」を決めるのに対し、theme.json の settings は「その UI にどんな選択肢を出すか」を決める、という役割分担も押さえておきましょう。functions.php の add_theme_support() に散らばっていた設定を1つの JSON に集約できるので、これからテーマを作るなら theme.json を軸に設計するのがおすすめです。

参考ページ

• Global Settings and Styles (theme.json) – Theme Handbook | Developer.WordPress.org
• Settings – Theme Handbook | Developer.WordPress.org
• Styles – Theme Handbook | Developer.WordPress.org
• Theme.json Version 3 Reference – Block Editor Handbook | Developer.WordPress.org