【初心者OK】theme.jsonとは？WordPressテーマ設計が劇的に変わる理由と使い方完全ガイド

「ブロックエディターで色や余白を変えるたびに style.css を書き換え、functions.php に長いコードを追加して…。」――そんな煩雑なテーマ開発にお悩みではありませんか？　WordPress 5.8 以降で正式採用された theme.json を使えば、デザイン方針やエディターの挙動を“たった一つの JSON ファイル”に集約できます。しかし「従来のテーマ設計と何が違うの？」「実運用で本当にラクになるの？」といった疑問から一歩踏み出せずにいる方も多いはず。本記事では、style.css／functions.php と比較しながら theme.json の基礎と活用法を徹底解説し、導入時につまずきやすいポイントまで網羅します。

theme.jsonとは何か？従来のテーマ設計との違い

theme.jsonの基本的な役割と導入背景【WordPress 5.8以降対応】

WordPress 5.8以降で導入されたtheme.jsonは、WordPressテーマの設計方法を根本的に変える革新的な仕組みです。この新しいファイルが生まれた背景には、Gutenbergブロックエディターの急速な進化と、フルサイト編集（FSE）の本格導入があります。

従来のWordPressテーマ開発では、デザインの設定やカスタマイズ情報がstyle.css、functions.php、カスタマイザーなど複数の場所に分散していました。この分散により、テーマ全体の設定を把握するのが困難で、デザインの一貫性を保つのも大変でした。

theme.jsonは、これらの問題を解決するために生まれました。JSONファイルという統一されたフォーマットで、テーマのデザイン設定を一元管理できるようになりました。

具体的には、以下のような役割を果たします：

• グローバルスタイルの統一定義：サイト全体で使用する色、フォント、余白などの基本設定
• ブロックエディターの表示制御：エディター画面とフロントエンドの見た目を統一
• ユーザーインターフェースの最適化：管理画面での設定項目の表示・非表示制御
• テーマの機能制限：特定の機能を意図的に無効化し、デザインの一貫性を保持

なぜ今theme.jsonが必要なのでしょうか？答えは、WordPressの目指す「誰でも美しいサイトを作れる」という理念にあります。フルサイト編集の時代において、テーマ開発者とサイト運営者の間で、デザインの設定方法や制御範囲を明確に定義する必要があったのです。theme.jsonは、その橋渡し役として機能します。

style.css・functions.phpとの機能比較と使い分け

theme.jsonの登場により、従来のstyle.cssやfunctions.phpの役割は大きく変化しました。それぞれの特徴と使い分けを理解することが、効率的なテーマ開発の鍵となります。

style.cssの役割変化

従来の役割：

• サイト全体のデザイン定義
• レスポンシブデザインの実装
• ブロック固有のスタイリング
• カスタムプロパティ（CSS変数）の定義

theme.json導入後の役割：

• theme.jsonで定義できない複雑なスタイリング
• アニメーションやトランジション効果
• 詳細なレスポンシブ調整
• ブラウザ固有の対応

functions.phpの役割変化

従来の役割：

• テーマサポート機能の有効化
• カスタムカラーパレットの定義
• フォントサイズの設定
• エディタースタイルの読み込み

theme.json導入後の役割：

• 動的な処理やロジック
• サードパーティAPIとの連携
• セキュリティ関連の設定
• theme.jsonで対応できない高度な機能

使い分けの指針

theme.jsonに記述すべき内容：

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー"
        }
      ]
    }
  }
}

style.cssに記述すべき内容：

.custom-animation {
  transition: all 0.3s ease;
  transform: translateY(0);
}

.custom-animation:hover {
  transform: translateY(-5px);
}

functions.phpに記述すべき内容：

function custom_enqueue_scripts() {
    wp_enqueue_script('custom-js', get_template_directory_uri() . '/js/custom.js');
}
add_action('wp_enqueue_scripts', 'custom_enqueue_scripts');

この使い分けにより、コードの可読性と保守性が大幅に向上します。theme.jsonは「何を設定するか」、style.cssは「どう見せるか」、functions.phpは「どう動作するか」という明確な役割分担が生まれました。

theme.jsonで何ができる？デザインを一元管理する強力な設定項目

theme.jsonの真価は、その豊富な設定項目にあります。従来は複数のファイルに分散していた設定を、一つのJSONファイルで管理できるようになりました。

色の管理

カラーパレットの定義から、テキストや背景の色設定まで、色に関するすべての設定を一元管理できます：

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー"
        },
        {
          "slug": "secondary",
          "color": "#005a87",
          "name": "セカンダリー"
        }
      ],
      "gradients": [
        {
          "slug": "primary-gradient",
          "gradient": "linear-gradient(45deg, #007cba 0%, #005a87 100%)",
          "name": "プライマリーグラデーション"
        }
      ]
    }
  }
}

タイポグラフィの制御

フォントファミリー、サイズ、行間、文字間隔など、文字に関するすべての設定を管理できます：

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "\\"Noto Sans JP\\", sans-serif",
          "slug": "noto-sans-jp",
          "name": "Noto Sans JP"
        }
      ],
      "fontSizes": [
        {
          "slug": "small",
          "size": "14px",
          "name": "小"
        },
        {
          "slug": "medium",
          "size": "16px",
          "name": "中"
        },
        {
          "slug": "large",
          "size": "20px",
          "name": "大"
        }
      ]
    }
  }
}

レイアウトとスペーシング

余白、パディング、コンテンツ幅など、レイアウトに関する設定も一元管理できます：

{
  "settings": {
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    },
    "spacing": {
      "spacingSizes": [
        {
          "slug": "small",
          "size": "16px",
          "name": "小"
        },
        {
          "slug": "medium",
          "size": "32px",
          "name": "中"
        }
      ]
    }
  }
}

ブロック単位の細かな制御

個々のブロックに対して、使用可能な機能や設定を制御できます：

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": {
          "text": true,
          "background": false
        },
        "typography": {
          "fontSize": true,
          "lineHeight": true
        }
      }
    }
  }
}

一元管理のメリット

1. デザインの一貫性：すべての設定が一箇所に集約されるため、デザインの統一性が保たれます
2. メンテナンス性の向上：変更が必要な際も、theme.jsonを編集するだけで済みます
3. 開発効率の向上：設定の所在が明確になり、開発時間が短縮されます
4. エラーの削減：JSONの構造化された記述により、設定ミスを防げます
5. チーム開発の促進：設定方法が標準化され、チーム間での引き継ぎが円滑になります

theme.jsonによる一元管理は、WordPressテーマ開発を次のレベルへと押し上げる革新的な仕組みです。

theme.jsonの記述方法と設計のベストプラクティス

最小構成のtheme.jsonサンプルコードと構文解説

theme.jsonを始めるには、まず基本的な構文とファイル構造を理解することが重要です。ここでは、読者がすぐに試せる最小構成のサンプルコードから始めて、段階的に理解を深めていきましょう。

最小構成のtheme.json

まずは、最もシンプルなtheme.jsonの例から見てみましょう：

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー"
        }
      ]
    }
  }
}

この最小構成でも、すでにサイト全体で使用できるカスタムカラーを定義できています。わずか15行のコードで、テーマの基本的な色設定が完了するのです。

JSON構文の基本ルール

theme.jsonはJSON（JavaScript Object Notation）形式で記述するため、以下の構文ルールを必ず守る必要があります：

1. 波括弧（{}）でオブジェクトを定義

{
  "key": "value"
}

2. 角括弧（[]）で配列を定義

{
  "items": ["item1", "item2", "item3"]
}

3. キーと値は必ずダブルクォーテーションで囲む

{
  "correct": "正しい記述",
  "incorrect": '間違った記述（シングルクォートは使えません）'
}

4. 最後の要素にはカンマを付けない

{
  "first": "値1",
  "second": "値2",
  "third": "値3"  // 最後にカンマは不要
}

5. 数値にはクォーテーション不要

{
  "fontSize": 16,
  "lineHeight": 1.5
}

WordPress 6.x系での推奨記述方法

WordPress 6.x系では、theme.jsonのバージョン2を使用することが強く推奨されています。バージョン2では、より柔軟な設定が可能になり、パフォーマンスも向上しています：

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true,
    "color": {
      "defaultPalette": false,
      "custom": true
    },
    "typography": {
      "customFontSize": true,
      "lineHeight": true,
      "dropCap": false
    }
  }
}

ファイルの配置場所

theme.jsonファイルは、テーマのルートディレクトリに配置します：

your-theme/
├── style.css
├── index.php
├── functions.php
└── theme.json  ← ここに配置

子テーマを使用している場合は、子テーマのルートディレクトリに配置することで、親テーマの設定を上書きできます。

settings/styles/customTemplatesの書き方と意味

theme.jsonは、主に3つのトップレベルキーで構成されています。それぞれの役割と記述方法を詳しく解説します。

settings：サイト全体の基本設定

settingsセクションは、サイト全体で使用する基本的な設定を定義します。ここで定義した設定は、ブロックエディターの設定パネルにも反映されます。

{
  "version": 2,
  "settings": {
    "color": {
      "defaultPalette": false,
      "custom": true,
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー"
        },
        {
          "slug": "secondary",
          "color": "#005a87",
          "name": "セカンダリー"
        },
        {
          "slug": "accent",
          "color": "#ff6b35",
          "name": "アクセント"
        }
      ],
      "gradients": [
        {
          "slug": "primary-to-secondary",
          "gradient": "linear-gradient(135deg, var(--wp--preset--color--primary) 0%, var(--wp--preset--color--secondary) 100%)",
          "name": "プライマリーからセカンダリー"
        }
      ]
    },
    "typography": {
      "customFontSize": true,
      "lineHeight": true,
      "dropCap": false,
      "fontFamilies": [
        {
          "fontFamily": "\\"Noto Sans JP\\", sans-serif",
          "slug": "noto-sans-jp",
          "name": "Noto Sans JP"
        },
        {
          "fontFamily": "\\"Roboto\\", sans-serif",
          "slug": "roboto",
          "name": "Roboto"
        }
      ],
      "fontSizes": [
        {
          "slug": "x-small",
          "size": "12px",
          "name": "極小"
        },
        {
          "slug": "small",
          "size": "14px",
          "name": "小"
        },
        {
          "slug": "medium",
          "size": "16px",
          "name": "中"
        },
        {
          "slug": "large",
          "size": "20px",
          "name": "大"
        },
        {
          "slug": "x-large",
          "size": "24px",
          "name": "極大"
        }
      ]
    },
    "spacing": {
      "customPadding": true,
      "customMargin": true,
      "spacingSizes": [
        {
          "slug": "small",
          "size": "16px",
          "name": "小"
        },
        {
          "slug": "medium",
          "size": "32px",
          "name": "中"
        },
        {
          "slug": "large",
          "size": "48px",
          "name": "大"
        }
      ]
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    }
  }
}

styles：実際のスタイル適用

stylesセクションでは、settingsで定義した設定を実際に要素に適用します。CSSのような役割を果たしますが、JSON形式で記述します。

{
  "version": 2,
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--primary)",
      "text": "#ffffff"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--noto-sans-jp)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "spacing": {
      "padding": {
        "top": "var(--wp--preset--spacing--medium)",
        "bottom": "var(--wp--preset--spacing--medium)"
      }
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--accent)"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--secondary)"
          }
        }
      },
      "h1": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--x-large)",
          "fontWeight": "700"
        },
        "color": {
          "text": "var(--wp--preset--color--secondary)"
        }
      }
    },
    "blocks": {
      "core/paragraph": {
        "typography": {
          "lineHeight": "1.8"
        },
        "spacing": {
          "margin": {
            "bottom": "var(--wp--preset--spacing--small)"
          }
        }
      },
      "core/heading": {
        "typography": {
          "fontWeight": "600"
        },
        "spacing": {
          "margin": {
            "top": "var(--wp--preset--spacing--large)",
            "bottom": "var(--wp--preset--spacing--medium)"
          }
        }
      }
    }
  }
}

customTemplates：カスタムテンプレートの定義

customTemplatesセクションでは、フルサイト編集で使用するカスタムテンプレートを定義できます。これは主にブロックテーマで使用されます。

{
  "version": 2,
  "customTemplates": [
    {
      "name": "page-about",
      "title": "About Page",
      "postTypes": ["page"]
    },
    {
      "name": "single-product",
      "title": "Product Single",
      "postTypes": ["product"]
    }
  ],
  "templateParts": [
    {
      "name": "header-minimal",
      "title": "Minimal Header",
      "area": "header"
    },
    {
      "name": "footer-simple",
      "title": "Simple Footer",
      "area": "footer"
    }
  ]
}

よくあるエラーとJSON構文ミスの防ぎ方・デバッグ方法

theme.jsonの記述で最も多いのが構文エラーです。エラーを防ぎ、問題が発生した際の対処法を身につけることが重要です。

よくある構文エラーと対処法

1. カンマ関連のエラー

最も頻発するエラーです：

// ❌ 間違い：最後の要素にカンマがある
{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー",  // ← このカンマが原因でエラー
        }
      ]
    }
  }
}

// ✅ 正しい：最後の要素にカンマなし
{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "プライマリー"
        }
      ]
    }
  }
}

2. クォーテーションマークのエラー

// ❌ 間違い：シングルクォートを使用
{
  'version': 2,
  'settings': {
    'color': {
      'custom': true
    }
  }
}

// ✅ 正しい：ダブルクォートを使用
{
  "version": 2,
  "settings": {
    "color": {
      "custom": true
    }
  }
}

3. 括弧の対応エラー

// ❌ 間違い：括弧が閉じられていない
{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba"
        }
      // ← 配列の閉じ括弧が不足
    }
  }
}

JSON構文チェックツール

エラーを事前に防ぐために、以下のツールを活用しましょう：

1. オンラインJSON Validator

• JSONLint（https://jsonlint.com/）
• JSON Formatter & Validator（https://jsonformatter.curiousconcept.com/）

2. コードエディターの活用

• Visual Studio Code：JSON用の拡張機能を導入
• Sublime Text：JSONの構文ハイライト機能を有効化
• Atom：linter-jsonlintパッケージの導入

3. WordPress内でのバリデーション

functions.phpに以下のコードを追加して、theme.jsonの妥当性をチェックできます：

function validate_theme_json() {
    $theme_json_path = get_template_directory() . '/theme.json';

    if (file_exists($theme_json_path)) {
        $theme_json_content = file_get_contents($theme_json_path);
        $decoded = json_decode($theme_json_content, true);

        if (json_last_error() !== JSON_ERROR_NONE) {
            add_action('admin_notices', function() {
                echo '<div class="notice notice-error"><p>theme.jsonに構文エラーがあります: ' . json_last_error_msg() . '</p></div>';
            });
        }
    }
}
add_action('after_setup_theme', 'validate_theme_json');

サイトが真っ白になった場合の対処法

theme.jsonのエラーによりサイトが表示されなくなった場合の対処手順：

1. WordPressデバッグモードの有効化

wp-config.phpに以下を追加：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);

2. エラーログの確認

/wp-content/debug.logファイルでエラー内容を確認します。

3. theme.jsonファイルの一時的な無効化

FTPまたはcPanelを使用して、theme.jsonファイルを一時的にリネーム（例：theme.json.backup）します。

4. 段階的な復旧

最小構成のtheme.jsonから始めて、徐々に設定を追加していきます：

{
  "version": 2
}

5. バックアップの重要性

theme.jsonを編集する前は、必ずバックアップを取得しましょう：

cp theme.json theme.json.backup

これらの対策により、theme.jsonの記述エラーを防ぎ、万が一問題が発生した場合も迅速に復旧できるようになります。

theme.jsonでできるカスタマイズ実践集

カラーパレット・フォント・余白などデザイン一元管理の具体例

theme.jsonの真の力は、実際のデザインカスタマイズにおいて発揮されます。ここでは、プロレベルのデザインを実現する具体的な設定例を、実践的なシナリオと共に紹介します。

デザイナーも納得！プロレベルのカラーパレット設計

企業サイトやブランドサイトで使用される、統一感のあるカラーパレットを構築してみましょう。以下は、信頼感と親しみやすさを両立したカラーパレットの例です：

{
  "version": 2,
  "settings": {
    "color": {
      "defaultPalette": false,
      "custom": true,
      "customGradient": true,
      "palette": [
        {
          "slug": "primary",
          "color": "#2563eb",
          "name": "プライマリーブルー"
        },
        {
          "slug": "primary-light",
          "color": "#60a5fa",
          "name": "ライトブルー"
        },
        {
          "slug": "primary-dark",
          "color": "#1d4ed8",
          "name": "ダークブルー"
        },
        {
          "slug": "secondary",
          "color": "#f59e0b",
          "name": "セカンダリーオレンジ"
        },
        {
          "slug": "accent",
          "color": "#ef4444",
          "name": "アクセントレッド"
        },
        {
          "slug": "neutral-50",
          "color": "#f9fafb",
          "name": "ニュートラル50"
        },
        {
          "slug": "neutral-200",
          "color": "#e5e7eb",
          "name": "ニュートラル200"
        },
        {
          "slug": "neutral-600",
          "color": "#4b5563",
          "name": "ニュートラル600"
        },
        {
          "slug": "neutral-900",
          "color": "#111827",
          "name": "ニュートラル900"
        }
      ],
      "gradients": [
        {
          "slug": "primary-gradient",
          "gradient": "linear-gradient(135deg, var(--wp--preset--color--primary) 0%, var(--wp--preset--color--primary-light) 100%)",
          "name": "プライマリーグラデーション"
        },
        {
          "slug": "sunset-gradient",
          "gradient": "linear-gradient(45deg, var(--wp--preset--color--secondary) 0%, var(--wp--preset--color--accent) 100%)",
          "name": "サンセットグラデーション"
        },
        {
          "slug": "subtle-gradient",
          "gradient": "linear-gradient(180deg, var(--wp--preset--color--neutral-50) 0%, var(--wp--preset--color--neutral-200) 100%)",
          "name": "サブトルグラデーション"
        }
      ]
    }
  }
}

この設定により、ブロックエディターのカラーピッカーには統一されたブランドカラーのみが表示され、デザインの一貫性が保たれます。また、CSS変数として自動生成されるため、カスタムCSSでも簡単に参照できます。

Google Fontsと日本語フォントの最適な組み合わせ

現代的で読みやすいタイポグラフィを実現するフォント設定を見てみましょう：

{
  "version": 2,
  "settings": {
    "typography": {
      "customFontSize": true,
      "fontStyle": true,
      "fontWeight": true,
      "lineHeight": true,
      "textDecoration": true,
      "writingMode": false,
      "fontFamilies": [
        {
          "fontFamily": "\\"Inter\\", \\"Noto Sans JP\\", -apple-system, BlinkMacSystemFont, \\"Segoe UI\\", sans-serif",
          "slug": "primary-sans",
          "name": "プライマリーサンセリフ"
        },
        {
          "fontFamily": "\\"Playfair Display\\", \\"Noto Serif JP\\", Georgia, serif",
          "slug": "heading-serif",
          "name": "見出し用セリフ"
        },
        {
          "fontFamily": "\\"JetBrains Mono\\", \\"SFMono-Regular\\", Consolas, monospace",
          "slug": "monospace",
          "name": "モノスペース"
        }
      ],
      "fontSizes": [
        {
          "slug": "x-small",
          "size": "0.75rem",
          "name": "極小（12px）"
        },
        {
          "slug": "small",
          "size": "0.875rem",
          "name": "小（14px）"
        },
        {
          "slug": "medium",
          "size": "1rem",
          "name": "中（16px）"
        },
        {
          "slug": "large",
          "size": "1.125rem",
          "name": "大（18px）"
        },
        {
          "slug": "x-large",
          "size": "1.25rem",
          "name": "極大（20px）"
        },
        {
          "slug": "xx-large",
          "size": "1.5rem",
          "name": "特大（24px）"
        },
        {
          "slug": "xxx-large",
          "size": "2rem",
          "name": "超特大（32px）"
        },
        {
          "slug": "huge",
          "size": "2.5rem",
          "name": "巨大（40px）"
        }
      ]
    }
  }
}

レスポンシブ対応のスペーシングシステム

モバイルからデスクトップまで一貫したデザインを実現するスペーシング設定：

{
  "version": 2,
  "settings": {
    "spacing": {
      "customPadding": true,
      "customMargin": true,
      "blockGap": true,
      "spacingSizes": [
        {
          "slug": "xs",
          "size": "0.25rem",
          "name": "XS（4px）"
        },
        {
          "slug": "sm",
          "size": "0.5rem",
          "name": "SM（8px）"
        },
        {
          "slug": "md",
          "size": "1rem",
          "name": "MD（16px）"
        },
        {
          "slug": "lg",
          "size": "1.5rem",
          "name": "LG（24px）"
        },
        {
          "slug": "xl",
          "size": "2rem",
          "name": "XL（32px）"
        },
        {
          "slug": "2xl",
          "size": "3rem",
          "name": "2XL（48px）"
        },
        {
          "slug": "3xl",
          "size": "4rem",
          "name": "3XL（64px）"
        },
        {
          "slug": "4xl",
          "size": "6rem",
          "name": "4XL（96px）"
        }
      ]
    },
    "layout": {
      "contentSize": "65rem",
      "wideSize": "85rem"
    }
  }
}

実際のスタイル適用でデザインを完成

設定したカラーパレットとフォントを実際に適用してみましょう：

{
  "version": 2,
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--neutral-50)",
      "text": "var(--wp--preset--color--neutral-900)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--primary-sans)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "spacing": {
      "padding": {
        "top": "var(--wp--preset--spacing--lg)",
        "bottom": "var(--wp--preset--spacing--lg)",
        "left": "var(--wp--preset--spacing--md)",
        "right": "var(--wp--preset--spacing--md)"
      }
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
          "textDecoration": "none"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--primary-dark)"
          },
          "typography": {
            "textDecoration": "underline"
          }
        }
      },
      "h1": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading-serif)",
          "fontSize": "var(--wp--preset--font-size--huge)",
          "fontWeight": "700",
          "lineHeight": "1.2"
        },
        "color": {
          "text": "var(--wp--preset--color--neutral-900)"
        },
        "spacing": {
          "margin": {
            "top": "var(--wp--preset--spacing--3xl)",
            "bottom": "var(--wp--preset--spacing--xl)"
          }
        }
      },
      "h2": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading-serif)",
          "fontSize": "var(--wp--preset--font-size--xxx-large)",
          "fontWeight": "600"
        },
        "color": {
          "text": "var(--wp--preset--color--primary)"
        }
      },
      "button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--neutral-50)"
        },
        "typography": {
          "fontWeight": "600"
        },
        "spacing": {
          "padding": {
            "top": "var(--wp--preset--spacing--sm)",
            "bottom": "var(--wp--preset--spacing--sm)",
            "left": "var(--wp--preset--spacing--lg)",
            "right": "var(--wp--preset--spacing--lg)"
          }
        },
        "border": {
          "radius": "0.375rem"
        },
        ":hover": {
          "color": {
            "background": "var(--wp--preset--color--primary-dark)"
          }
        }
      }
    }
  }
}

この設定により、サイト全体で統一されたプロフェッショナルなデザインが実現されます。

ブロックエディター（Gutenberg）とフルサイト編集（FSE）連携パターン

theme.jsonの最大の強みは、ブロックエディターとフロントエンドの見た目を完全に統一できることです。ここでは、具体的な連携パターンを解説します。

エディター画面とフロントエンドの統一

管理画面での編集体験をフロントエンドと同一にする設定：

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true,
    "color": {
      "defaultPalette": false,
      "defaultGradients": false,
      "customGradient": false
    },
    "typography": {
      "customFontSize": false,
      "fontSizes": [
        {
          "slug": "small",
          "size": "0.875rem",
          "name": "小"
        },
        {
          "slug": "medium",
          "size": "1rem",
          "name": "中"
        },
        {
          "slug": "large",
          "size": "1.5rem",
          "name": "大"
        }
      ]
    }
  }
}

appearanceTools: trueにより、ボーダー、カラー、タイポグラフィ、スペーシングの設定パネルが統合され、より直感的な編集体験が提供されます。

ブロック単位の細かな制御

各ブロックに対して、使用可能な機能を制限することで、デザインの一貫性を保ちます：

{
  "version": 2,
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": {
          "text": true,
          "background": false,
          "link": true
        },
        "typography": {
          "fontSize": true,
          "lineHeight": true,
          "fontStyle": false,
          "fontWeight": false
        }
      },
      "core/heading": {
        "color": {
          "text": true,
          "background": false
        },
        "typography": {
          "fontSize": false,
          "fontFamily": false
        }
      },
      "core/button": {
        "color": {
          "text": true,
          "background": true,
          "gradient": true
        },
        "spacing": {
          "padding": true,
          "margin": false
        },
        "border": {
          "color": true,
          "radius": true,
          "style": true,
          "width": true
        }
      },
      "core/image": {
        "border": {
          "color": true,
          "radius": true,
          "style": true,
          "width": true
        },
        "spacing": {
          "margin": true,
          "padding": false
        }
      }
    }
  }
}

フルサイト編集（FSE）対応テーマでの活用

Twenty Twenty-Fourのような最新のブロックテーマでは、theme.jsonがテンプレート構造と密接に連携します：

{
  "version": 2,
  "settings": {
    "layout": {
      "contentSize": "620px",
      "wideSize": "1240px"
    }
  },
  "styles": {
    "blocks": {
      "core/post-title": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading-serif)",
          "fontSize": "var(--wp--preset--font-size--xxx-large)",
          "fontWeight": "400",
          "lineHeight": "1.2"
        },
        "spacing": {
          "margin": {
            "bottom": "var(--wp--preset--spacing--lg)"
          }
        }
      },
      "core/post-content": {
        "typography": {
          "lineHeight": "1.8"
        }
      },
      "core/site-title": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading-serif)",
          "fontSize": "var(--wp--preset--font-size--large)",
          "fontWeight": "600"
        },
        "elements": {
          "link": {
            "color": {
              "text": "var(--wp--preset--color--neutral-900)"
            },
            "typography": {
              "textDecoration": "none"
            }
          }
        }
      },
      "core/navigation": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--medium)",
          "fontWeight": "500"
        },
        "elements": {
          "link": {
            "color": {
              "text": "var(--wp--preset--color--neutral-600)"
            },
            ":hover": {
              "color": {
                "text": "var(--wp--preset--color--primary)"
              }
            }
          }
        }
      }
    }
  }
}

テンプレートパーツとの連携

ヘッダーやフッターなどのテンプレートパーツに対する統一的なスタイリング：

{
  "version": 2,
  "styles": {
    "blocks": {
      "core/template-part": {
        "spacing": {
          "padding": {
            "top": "var(--wp--preset--spacing--lg)",
            "bottom": "var(--wp--preset--spacing--lg)"
          }
        }
      }
    }
  },
  "customTemplates": [
    {
      "name": "page-landing",
      "title": "ランディングページ",
      "postTypes": ["page"]
    }
  ],
  "templateParts": [
    {
      "name": "header-transparent",
      "title": "透明ヘッダー",
      "area": "header"
    },
    {
      "name": "footer-minimal",
      "title": "ミニマルフッター",
      "area": "footer"
    }
  ]
}

theme.json導入・運用で失敗しないための応用テクニック

既存テーマへの段階的導入と子テーマでの利用法

運用中サイトへの安全な導入戦略

既存のWordPressサイトにtheme.jsonを導入する際は、いきなり全ての設定を移行するのではなく、段階的なアプローチが重要です。特に本格運用中のサイトでは、以下の手順で慎重に進めることをお勧めします。

ステップ1: 開発環境での事前検証

まずは本番環境のコピーを作成し、開発環境でtheme.jsonの動作を確認します。この段階で既存のCSSやPHPの設定との競合がないかをチェックしましょう。

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "メインカラー",
          "slug": "main",
          "color": "#0073aa"
        }
      ]
    }
  }
}

ステップ2: 最小構成からのスタート

最初は色やフォントサイズなど、影響範囲の小さい設定から始めます。この段階で既存デザインとの親和性を確認し、問題がなければ徐々に設定項目を増やしていきます。

ステップ3: A/Bテストによる検証

可能であれば、一部のページやセクションでのみtheme.jsonを適用し、ユーザビリティテストを実施します。表示速度や管理画面での操作性に問題がないかを入念にチェックしましょう。

子テーマでのtheme.json活用法と継承ルール

子テーマでtheme.jsonを使用する場合、親テーマの設定との関係を正しく理解することが重要です。WordPressでは以下の優先順位で設定が適用されます：

1. 子テーマのtheme.json
2. 親テーマのtheme.json
3. WordPressコアのデフォルト設定

子テーマでの設定例

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "ブランドカラー",
          "slug": "brand",
          "color": "#ff6b35"
        },
        {
          "name": "アクセントカラー",
          "slug": "accent",
          "color": "#f7931e"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "name": "見出し大",
          "slug": "heading-large",
          "size": "2.5rem"
        }
      ]
    }
  },
  "styles": {
    "blocks": {
      "core/heading": {
        "color": {
          "text": "var(--wp--preset--color--brand)"
        }
      }
    }
  }
}

継承と上書きの注意点

• settingsセクションは配列の場合、子テーマの設定が親テーマに追加されます
• stylesセクションは子テーマの設定が親テーマを完全に上書きします
• 特定のブロックのスタイルのみを変更したい場合は、他のプロパティも明示的に指定する必要があります

デザイナーも納得！すぐに使えるtheme.jsonテンプレートとGUI生成ツール

プロ仕様のtheme.jsonテンプレート

デザイナーとの協業がスムーズに進む、実用的なtheme.jsonテンプレートをご紹介します。このテンプレートは、多くのWebサイトで使用される基本的なデザインシステムを網羅しています。

{
  "version": 2,
  "settings": {
    "color": {
      "duotone": [],
      "gradients": [],
      "palette": [
        {
          "name": "プライマリー",
          "slug": "primary",
          "color": "#2563eb"
        },
        {
          "name": "セカンダリー",
          "slug": "secondary",
          "color": "#7c3aed"
        },
        {
          "name": "成功",
          "slug": "success",
          "color": "#059669"
        },
        {
          "name": "警告",
          "slug": "warning",
          "color": "#d97706"
        },
        {
          "name": "エラー",
          "slug": "error",
          "color": "#dc2626"
        },
        {
          "name": "テキスト",
          "slug": "text",
          "color": "#1f2937"
        },
        {
          "name": "背景",
          "slug": "background",
          "color": "#ffffff"
        },
        {
          "name": "グレー-100",
          "slug": "gray-100",
          "color": "#f3f4f6"
        },
        {
          "name": "グレー-300",
          "slug": "gray-300",
          "color": "#d1d5db"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "name": "メイン",
          "slug": "main",
          "fontFamily": "'Noto Sans JP', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
        },
        {
          "name": "見出し",
          "slug": "heading",
          "fontFamily": "'Noto Serif JP', Georgia, serif"
        },
        {
          "name": "モノスペース",
          "slug": "monospace",
          "fontFamily": "'SF Mono', Monaco, 'Cascadia Code', monospace"
        }
      ],
      "fontSizes": [
        {
          "name": "極小",
          "slug": "x-small",
          "size": "0.75rem"
        },
        {
          "name": "小",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "標準",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "大",
          "slug": "large",
          "size": "1.25rem"
        },
        {
          "name": "特大",
          "slug": "x-large",
          "size": "1.5rem"
        },
        {
          "name": "見出しM",
          "slug": "heading-medium",
          "size": "2rem"
        },
        {
          "name": "見出しL",
          "slug": "heading-large",
          "size": "2.5rem"
        },
        {
          "name": "見出しXL",
          "slug": "heading-x-large",
          "size": "3rem"
        }
      ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "vh", "vw", "%"],
      "spacingScale": {
        "steps": 0,
        "mediumStep": 1.5,
        "increment": 1.5,
        "operator": "*",
        "unit": "rem"
      },
      "spacingSizes": [
        {
          "name": "極小",
          "slug": "x-small",
          "size": "0.5rem"
        },
        {
          "name": "小",
          "slug": "small",
          "size": "1rem"
        },
        {
          "name": "標準",
          "slug": "medium",
          "size": "1.5rem"
        },
        {
          "name": "大",
          "slug": "large",
          "size": "2rem"
        },
        {
          "name": "特大",
          "slug": "x-large",
          "size": "3rem"
        }
      ]
    },
    "border": {
      "radius": true,
      "color": true,
      "style": true,
      "width": true
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--background)",
      "text": "var(--wp--preset--color--text)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--main)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "spacing": {
      "blockGap": "var(--wp--preset--spacing--medium)"
    },
    "blocks": {
      "core/heading": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading)",
          "fontWeight": "700",
          "lineHeight": "1.2"
        },
        "spacing": {
          "margin": {
            "bottom": "var(--wp--preset--spacing--small)"
          }
        }
      },
      "core/paragraph": {
        "spacing": {
          "margin": {
            "bottom": "var(--wp--preset--spacing--small)"
          }
        }
      },
      "core/button": {
        "border": {
          "radius": "6px"
        },
        "spacing": {
          "padding": {
            "top": "0.75rem",
            "bottom": "0.75rem",
            "left": "1.5rem",
            "right": "1.5rem"
          }
        }
      }
    }
  }
}

GUI生成ツールの活用法

theme.jsonを直感的に作成・編集できるGUIツールを活用することで、コーディングの負担を大幅に軽減できます。

1. WordPress Site Editor（サイトエディター）

WordPress 6.0以降に標準搭載されているサイトエディターは、theme.jsonの設定を視覚的に編集できる強力なツールです。

• スタイル > グローバルスタイルから、カラー、タイポグラフィ、レイアウトを直接調整
• 変更内容は自動的にtheme.jsonに反映される
• リアルタイムプレビューで設定結果を即座に確認可能

使用手順：

1. WordPress管理画面から「外観」>「テーマエディター」にアクセス
2. 「スタイル」タブをクリック
3. 「サイト全体を編集」から各種設定を調整
4. 「保存」で変更を確定

2. Create Block Theme プラグイン

WordPressの公式チームが開発したプラグインで、theme.jsonを含むブロックテーマの作成を支援します。

// プラグインインストール後、以下の機能が利用可能
// - 既存テーマからのtheme.json生成
// - サイトエディターの設定をtheme.jsonにエクスポート
// - カスタムテンプレートの作成支援

3. ThemeForge（サードパーティツール）

ブラウザベースのtheme.json生成ツールで、コーディング知識がなくても直感的に設定できます。

• ドラッグ&ドロップでカラーパレットを作成
• Google Fontsとの直接連携
• 生成されたJSONコードのワンクリックコピー

PHPやCSSとの使い分けは？theme.jsonで制御できる範囲と限界

theme.jsonの適用範囲

theme.jsonで制御できる範囲を明確に理解することで、効率的なテーマ開発が可能になります。

theme.jsonが得意な領域：

• グローバルなデザインシステムの定義
• ブロックエディターとフロントエンドの統一
• ユーザーが変更可能な設定項目の制御
• レスポンシブデザインの基本設定

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true,
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "spacing": {
      "blockGap": "clamp(1rem, 4vw, 2rem)"
    }
  }
}

他の技術との適切な使い分け

functions.phpで対応すべき機能：

<?php
// 動的なスタイル生成
function my_theme_dynamic_styles() {
    $primary_color = get_theme_mod('primary_color', '#0073aa');
    $font_size = get_theme_mod('base_font_size', 16);

    $css = "
        :root {
            --dynamic-primary: {$primary_color};
            --dynamic-font-size: {$font_size}px;
        }
    ";

    wp_add_inline_style('theme-style', $css);
}
add_action('wp_enqueue_scripts', 'my_theme_dynamic_styles');

// 条件分岐によるスタイル制御
function my_theme_conditional_styles() {
    if (is_front_page()) {
        wp_enqueue_style('front-page-style', get_template_directory_uri() . '/assets/css/front-page.css');
    }
}
add_action('wp_enqueue_scripts', 'my_theme_conditional_styles');

カスタムCSSで対応すべき領域：

/* 複雑なアニメーション */
.custom-animation {
    animation: slideIn 0.5s ease-out;
    transform: translateX(0);
}

@keyframes slideIn {
    from {
        transform: translateX(-100%);
        opacity: 0;
    }
    to {
        transform: translateX(0);
        opacity: 1;
    }
}

/* 詳細なレスポンシブ制御 */
@media (min-width: 768px) and (max-width: 1024px) {
    .tablet-specific {
        grid-template-columns: repeat(2, 1fr);
        gap: 1.5rem;
    }
}

/* ブラウザ固有のハック */
@supports (display: grid) {
    .grid-layout {
        display: grid;
        grid-template-columns: 1fr 300px;
    }
}

theme.jsonの限界と代替案

theme.jsonでは実現困難なケース：

JavaScript連携が必要な動的スタイル

// ユーザーの操作に応じたスタイル変更
document.addEventListener('scroll', () => {
    const header = document.querySelector('.site-header');
    if (window.scrollY > 100) {
        header.classList.add('scrolled');
    } else {
        header.classList.remove('scrolled');
    }
});

サードパーティライブラリとの統合

// Lightboxライブラリなどの外部CSSとの協調
function enqueue_lightbox_styles() {
    wp_enqueue_style('lightbox', 'path/to/lightbox.css');
    // theme.jsonの設定と衝突しないよう優先度を調整
    wp_enqueue_style('theme-lightbox-fix', get_template_directory_uri() . '/assets/css/lightbox-fix.css', ['lightbox']);
}

複雑な計算や条件分岐

// SCSSを使用した複雑な計算
$base-font-size: 1rem;
$modular-scale: 1.25;

@for $i from 1 through 6 {
    .heading-#{$i} {
        font-size: $base-font-size * pow($modular-scale, 6 - $i);
        margin-bottom: $base-font-size * pow($modular-scale, 6 - $i) * 0.5;
    }
}

効果的な組み合わせパターン

最も効果的なアプローチは、各技術の特性を活かした適材適所の使い分けです：

// theme.json: 基本的なデザインシステム
{
  "version": 2,
  "settings": {
    "custom": {
      "baseUnit": "1rem",
      "borderRadius": "6px"
    }
  }
}

// functions.php: theme.jsonの設定を活用した動的処理
function get_theme_setting($key) {
    $theme_json = json_decode(file_get_contents(get_template_directory() . '/theme.json'), true);
    return $theme_json['settings']['custom'][$key] ?? null;
}

function enqueue_dynamic_styles() {
    $base_unit = get_theme_setting('baseUnit');
    $border_radius = get_theme_setting('borderRadius');

    $css = "
        .dynamic-component {
            padding: calc({$base_unit} * 2);
            border-radius: {$border_radius};
        }
    ";

    wp_add_inline_style('theme-style', $css);
}

この組み合わせにより、theme.jsonで定義した設計システムをPHPで動的に活用し、一貫性を保ちながら柔軟なカスタマイズが実現できます。

よくある質問（FAQ）

まとめ

theme.jsonの登場により、WordPressのテーマ開発は根本的な変革を迎えました。従来のstyle.cssやfunctions.phpに分散していた設定を一元管理できるようになり、デザインシステムの構築と維持が飛躍的に効率化されています。

WordPress 6.x系におけるtheme.jsonの活用により、以下の重要な変化が実現されました：

• デザインの一貫性向上
  色、フォント、スペーシング、レイアウトなどの設計要素を単一のファイルで管理することで、サイト全体のデザイン一貫性が大幅に向上しました。ブロックエディターとフロントエンドの表示が統一され、「管理画面で見た通りにサイトに表示される」というWYSIWYGの理想が現実となっています。
• 開発効率の飛躍的な向上
  グローバルスタイルの定義、ブロック固有の設定、カスタムテンプレートの管理を統合的に行えるため、開発時間の短縮と品質向上を同時に実現できます。特に大規模サイトや複数サイトの運営において、その効果は顕著に現れます。
• ユーザビリティの改善
  サイトエディターとの完全統合により、技術的な知識を持たないユーザーでも直感的にサイトのデザインをカスタマイズできるようになりました。これにより、WordPressの「民主化」という理念がさらに進展しています。

今後のWordPressサイト制作における重要性

theme.jsonは単なる新機能ではなく、WordPress エコシステム全体の進化方向を示す重要な指標です。フルサイト編集（FSE）の普及とともに、以下の分野での重要性がさらに高まることが予想されます：

• ブロックテーマの標準化
  WordPress公式テーマを筆頭に、多くのテーマがtheme.jsonベースの設計に移行しています。今後新規開発するテーマでは、theme.jsonの習得が必須スキルとなるでしょう。
• エンタープライズ領域での活用拡大
  大企業のコーポレートサイトやECサイトにおいて、ブランドガイドラインに沿った厳密なデザイン管理が求められています。theme.jsonによるデザインシステムの標準化は、これらの要求に対する理想的なソリューションとなります。
• 多言語・多地域サイトでの効率化
  グローバル展開する企業のWebサイトでは、地域ごとの文化的差異に配慮したデザイン調整が必要です。theme.jsonをベースとした柔軟なカスタマイズ機能により、効率的な多地域対応が可能になります。

theme.jsonは決して複雑な技術ではありません。この記事で紹介した基本的な概念とコード例を参考に、まずは小さなプロジェクトから始めてみてください。実際に手を動かしながら学ぶことで、theme.jsonの真の力を実感できるはずです。

WordPressブロックに独自スタイルを追加！カスタムCSS＆register_block_style徹底ガイド

WordPressブロックの独自スタイルでデザインの悩みを解決！Gutenbergで思い通りのサイトを構築しませんか？本記事では、カスタムCSSクラスの追加からregister_block_style()を使ったUI登録、functions.phpやtheme.jsonの活用法まで、初心者にもわかりやすく解説します。

watashi.xyz

2025.06.23

WordPressで自作データベース連携プラグインを作ろう！$wpdb活用やテーブル作成・更新の実装手順を完全解説！

WordPressでプラグインを自作し、独自データベースを活用する方法を徹底解説！テーブル設計やdbDelta()・$wpdbを使った作成手順、CRUD処理、管理画面UIの実装、SQLインジェクション対策まで、実例を交えて初心者にもわかりやすく紹介。拡張性と安全性を考慮した実践的な開発ノウハウを学べます！

watashi.xyz

2025.05.30

WordPress検索機能の自作手順を完全解説！カスタム投稿・絞り込みまで対応する実装方法とは？

WordPressの検索機能を自作する理由や標準機能の限界、プラグインでは実現できない要件、PHPによる柔軟なカスタマイズ方法を解説。searchform.phpやsearch.phpの役割から、カスタムフィールド・タクソノミーでの絞り込み、複数キーワード検索、検索結果ページの最適化まで、実践的な手順を紹介します

watashi.xyz

2025.05.12

WordPressウィジェット作り方完全ガイド｜自作・エリア追加・表示制御まで初心者向けに徹底解説！

WordPressでオリジナルのウィジェットを作成したい方必見。WP_Widgetクラスの基本、PHPコードの書き方、functions.phpへの登録方法を詳しく解説します。ウィジェットエリア追加や固定ページへの表示制御、デザイン調整、トラブル解決策まで網羅。あなたのサイトにぴったりのカスタムウィジェットを！

watashi.xyz

2025.05.09