WordPress初心者が知っておきたい「theme.json」とは？ 基本から使い方まで分かりやすく解説

WordPressのテーマ開発やカスタマイズについて調べていると、「theme.json」という言葉を目にする機会が増えてきました。

しかし、初心者の方にとっては、以下のように感じることも多いでしょう。

• functions.phpとの違いが分からない
• CSSを書けば十分では？
• 何のために存在するの？

実際のところ、theme.jsonは現代のWordPressテーマ開発において非常に重要な仕組みです。

特にブロックエディター（Gutenberg）やフルサイト編集（FSE）が主流になった現在では、テーマ全体のデザインや設定を管理する中心的な役割を担っています。

この記事では、theme.jsonの基本的な考え方から具体的な設定例まで、分かりやすく解説します。

theme.jsonとは？

theme.jsonとは、WordPressテーマの設定情報をJSON形式で管理するためのファイルです。

以下のように、テーマフォルダ直下に設置します。

wp-content
 └ themes
     └ my-theme
         ├ style.css
         ├ functions.php
         ├ theme.json ← このファイルがこの記事の主役です!!
         └ templatesCode language: plaintext (plaintext)

従来は「CSS」「functions.php」「add_theme_support()」などに分散していた設定を、theme.jsonへまとめて記述できるようになりました。

簡単に言えば、「テーマ全体のデザイン設定を一元管理するためのファイル」です。

なぜtheme.jsonが作られたのか？

昔のWordPressテーマでは、例えば以下のような形で管理されていました。

• 親テーマ functions.php： add_theme_support() → エディター設定
• 親テーマ style.css： デザイン設定
• 子テーマ style.css： 色や余白の調整

しかし、

• 設定場所が分散する
• メンテナンスが大変
• テーマごとの差が大きい

などのような問題がありました。そこで登場したのがtheme.jsonです。

theme.json でできること（一例）

theme.jsonでは、以下のような設定情報を統一的に管理できます。

• カラーパレット
• フォントサイズ
• 余白
• レイアウト
• ブロック設定

JSONとは？

theme.jsonの「JSON」はデータ記述形式の一種です。

例えば以下の記述は、「versionという項目の値は3」という意味になります。

{
  "version": 3
}Code language: JSON / JSON with Comments (json)

初心者のうちは、「テーマ設定を書くための専用ファイル」と理解しておけば十分です。

theme.jsonでできること

theme.jsonでは主に以下を管理できます。

カラー設定

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "name": "メインカラー",
          "color": "#0073aa"
        }
      ]
    }
  }
}
Code language: JSON / JSON with Comments (json)

このように記述すると、エディターのカラーパレットに色を追加できます。

フォントサイズ設定

{
  "settings": {
    "typography": {
      "fontSizes": [
        {
          "slug": "small",
          "size": "14px",
          "name": "小"
        }
      ]
    }
  }
}
Code language: JSON / JSON with Comments (json)

独自の文字サイズを登録できます。

レイアウト設定

{
  "settings": {
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}
Code language: JSON / JSON with Comments (json)

これにより、以下の幅を指定できます。

• 通常幅： settings.layout.contentSize
• ワイド幅（幅広）： settings.layout.wideSize

余白設定

{
  "settings": {
    "spacing": {
      "padding": true,
      "margin": true
    }
  }
}
Code language: JSON / JSON with Comments (json)

ブロックエディターから余白調整を利用できます。

ブロックごとの設定

特定ブロックだけ設定することも可能です。

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": {
          "background": false
        }
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

段落ブロックの背景色機能を無効化できます。

スタイル設定も可能

theme.jsonではデザイン指定もできます。

文字サイズの指定

例えば、以下の例では全体の文字サイズを指定できます。

{
  "styles": {
    "typography": {
      "fontSize": "18px"
    }
  }
}
Code language: JSON / JSON with Comments (json)

見出しのデザイン

{
  "styles": {
    "elements": {
      "h2": {
        "typography": {
          "fontSize": "2rem"
        }
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

H2見出しへ統一スタイルを適用できます。

functions.phpとの違い

初心者がよく混乱するポイントです。

簡単に言うと、機能はfunctions.php、デザイン設定はtheme.jsonという考え方になります。

functions.php

主な役割は以下の通りとなっています。

• PHP処理
• フック
• 機能追加
• カスタム処理

add_action(
    'wp_enqueue_scripts',
    'my_style'
);Code language: PHP (php)

theme.json

主な役割は以下の通りです。

• デザイン設定
• エディター設定
• レイアウト管理

{
  "settings": {
    "color": {
      "palette": []
    }
  }
}Code language: JSON / JSON with Comments (json)

CSSとの違い

こちらの区別も重要です。WordPressを通すか通さないかという観点からすると、大きな違いがあります。

theme.jsonは、例えば「外観＞エディター＞デザイン」の設定画面にも反映されるようになっています。最近のWordPressでは、「まずtheme.jsonで設定し、不足部分をCSSで補う」という考え方も十分通用するものとなっています。

CSS

見た目を直接指定するものであり、WordPressは処理には関与しません。

h2 {
  color:red;
}Code language: CSS (css)

theme.json

WordPressの仕組みを通じて設定するものであり、WordPressは処理に直接関与します。

{
  "styles": {
    "elements": {
      "h2": {
        "color": {
          "text": "#ff0000"
        }
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

ブロックテーマで特に重要

現在のWordPressでは、「Twenty Twenty-Five」「Twenty Twenty-Four」などの標準テーマでtheme.jsonが中心になっており、テーマの重要なデザイン情報がtheme.jsonで管理されています。

そのため、ブロックテーマを扱うならtheme.jsonの理解はほぼ必須と言えるでしょう。

クラシックテーマでも使える？

答えは「はい」です。

例えば、

• Lightning
• Cocoon
• SWELL

などでも利用できます。必ずしもブロックテーマ専用ではありません。

実際、例えばLightningではtheme.jsonが公式で利用できるようになっており、積極的に活用する動きもあります。

ブロックテーマとクラシックテーマの違いについては、以下の記事もご覧ください。

versionについて

theme.jsonの先頭には通常、以下のような記載があります。

{
  "version": 3
}Code language: JSON / JSON with Comments (json)

これはtheme.jsonの仕様バージョンです。

現在はVersion 3が主流です。新規作成時は基本的に"version": 3を使用すれば問題ありません。

初心者が最初に覚えたい設定

まずは以下だけ理解できれば十分です。

• カラーパレット： settings.color.palette
• フォントサイズ： settings.typography.fontSizes
• レイアウト幅： settings.layout
• 全体スタイル： styles

よくある失敗

JSONのカンマ忘れ・過剰

JSONでは区切り記号としてカンマが重要な役割を果たします。

以下は「3」の後にカンマがないため、エラーとなります。

{
  "version": 3
  "settings": {}
}
Code language: JSON / JSON with Comments (json)

逆に、以下は{}の後に余分なカンマがあるため、こちらもエラーとなります。

{
  "version": 3,
  "settings": {},
}Code language: JSON / JSON with Comments (json)

括弧の閉じ忘れ

JSONは {} や [] の対応関係が重要です。

以下のように1つでも欠けていたり、記号が誤っていたりするとエラーになります。

[
  "version": 3,
  "settings": {
}Code language: JSON / JSON with Comments (json)

CSS感覚で書いてしまう

theme.jsonはCSSではありません。

例えば、以下のような単純な書き方は基本的にできません。

{
  "color":"red"
}
Code language: JSON / JSON with Comments (json)

WordPressが定める構造に従う必要があります。

これからのWordPressとtheme.json

WordPressは今後もブロックエディター中心で進化していくと考えられています。

そのため、以下のような対応を行うならtheme.jsonの知識はますます重要になります。

• テーマ開発
• 子テーマ作成
• ブロックテーマ運用
• エディターカスタマイズ

昔はCSSやfunctions.phpだけでも十分でしたが、現在はtheme.jsonがテーマ設計の中心になりつつあります。

まとめ

theme.jsonは、現代のWordPressテーマにおける「設定の司令塔」とも言える存在です。

主に以下を管理できます。

• カラー設定
• フォント設定
• レイアウト設定
• 余白設定
• ブロック設定
• 全体デザイン

従来のWordPressではfunctions.phpやCSSに分散していた設定を、一箇所にまとめられるようになりました。特にブロックテーマやフルサイト編集を活用する場合、theme.jsonの理解は欠かせません。

最初は難しく感じるかもしれませんが、

• settings
• styles
• blocks

という3つの考え方（パラメータ）を覚えるだけでも十分な第一歩になります。

WordPressの新しいテーマ開発を学ぶうえで、ぜひ少しずつtheme.jsonに触れてみてください。