WordPress theme.jsonの書き方｜色・文字・余白をライブ生成して理解する

theme.jsonは、WordPressテーマの色・文字サイズ・余白・ブロック設定をJSONで一元管理するファイルです。settingsは編集者が選べる道具、stylesは初期デザイン、と分けると迷いません。まずライブ生成で違いを見てみましょう。

情報確認日：2026年8月20日

結論：theme.jsonは「選択肢」と「初期値」を分ける

色・文字・余白からtheme.jsonを生成する

theme.jsonを置く場所と最小構成

テーマのルート、つまりstyle.cssと同じ階層へtheme.jsonを置きます。ブロックテーマだけでなくクラシックテーマでも段階的に利用できます。

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {}
}

$schemaを付けると、対応エディターで補完や誤り検出を受けやすくなります。versionは利用するWordPressと公式リファレンスに合わせます。

settingsで編集者の選択肢を定義する

カラーパレット

{
  "settings": {
    "color": {
      "defaultPalette": false,
      "palette": [
        { "slug": "brand", "name": "ブランド", "color": "#2563eb" },
        { "slug": "ink", "name": "本文", "color": "#172033" }
      ]
    }
  }
}

slugはCSSカスタムプロパティやクラス名の一部になるため、表示名を変えても安定する英数字で決めます。既存slugの意味を後から別の色へ変えると、過去の投稿にも影響します。

文字サイズと余白

{
  "settings": {
    "typography": {
      "fontSizes": [
        { "slug": "body", "name": "本文", "size": "1rem" },
        { "slug": "hero", "name": "大見出し", "size": "clamp(2rem, 5vw, 4rem)" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "40", "name": "M", "size": "1.5rem" }
      ]
    }
  }
}

選択肢を増やしすぎると、投稿ごとの見た目がばらつきます。デザインシステムとして必要な段階だけを登録し、例外はテーマ側で管理します。

stylesでサイトとブロックの初期値を決める

{
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#172033"
    },
    "typography": {
      "fontSize": "var(--wp--preset--font-size--body)",
      "lineHeight": "1.8"
    },
    "blocks": {
      "core/button": {
        "border": { "radius": "0.6rem" },
        "color": {
          "background": "var(--wp--preset--color--brand)"
        }
      }
    }
  }
}

全体の値はstyles直下、特定ブロックはstyles.blocksへ置きます。CSSを完全になくす仕組みではありません。疑似要素、複雑な状態、詳細なレイアウトなどは通常のCSSが適します。

優先順位を理解する

WordPressのグローバルスタイルは、コア既定値、テーマ、子テーマ、ユーザーがサイトエディターで保存した設定などを統合します。theme.jsonを直しても変わらない場合、ユーザー保存済みのスタイルが上位から上書きしていることがあります。

安全な移行手順

1. 既存CSSから色、文字、余白の繰り返し値を洗い出す
2. 少数のプリセットをsettingsへ登録する
3. 新規ブロックだけで選択肢と公開表示を確認する
4. stylesへ共通初期値を移す
5. 重複したCSSを、影響範囲を確認しながら段階的に削る

既存サイトで一括置換すると、ユーザーが保存した個別設定やプラグインのCSSと衝突します。まずプリセットの追加だけから始めると戻しやすくなります。

よくある質問

まとめ

theme.jsonは、編集者へ渡す選択肢をsettings、テーマの初期見た目をstylesへ分けると理解しやすくなります。まず色・文字・余白の少数プリセットから始め、サイトエディターの上書きや既存CSSを確認しながら段階移行してください。

関連記事

• CSSの書き方
• CSSのHSLカラー設定
• WordPressブログの始め方

参照した公式資料

• WordPress Theme Handbook：Global Settings and Styles
• WordPress：theme.json Living Reference