WordPress テーマ開発レビュースキル

概要

WordPress 6.6+ 向けの体系的なテーマ開発レビューで、ブロックテーマ（フルサイト編集）を主焦点とし、クラシックテーマについては移行ガイダンスを提供します。コアの原則： WordPress テーマは大きなパラダイムシフトを経験しました。ブロックテーマは HTML テンプレート（ブロックマークアップ付き）と theme.json（グローバル設定/スタイル）を使用し、PHP テンプレートと add_theme_support() 呼び出しに代わるものとなりました。theme.json v3 は設計構成の単一の信頼できるソースです。レビューは theme.json 構造、ブロックテンプレート階層（templates/ 内の HTML ファイル）、テンプレートパーツ（parts/）、グローバルスタイル、スタイルバリエーション、テーマ内のブロックパターン、子テーマの互換性、およびクラシック・ツー・ブロック移行機会を検証します。テーマタイプ（ブロック/クラシック/ハイブリッド/子/WordPress.org）を自動検出し、ガイダンスに応じて調整します。行番号、重大度ラベル（CRITICAL/WARNING/INFO）、および BAD/GOOD コードペアで、ファイル（PHP、HTML テンプレート、JSON ファイルは実際のパス別に混在）でグループ化された調査結果をレポートします。

注記： このスキルは PHP ファイル（functions.php、クラシックテンプレート）、HTML ブロックテンプレートファイル（templates/、parts/）、JSON ファイル（theme.json、スタイルバリエーション）、および PHP パターンファイル（patterns/）をレビューします。PHP は WordPress PHP コーディング標準（括弧内のスペース、array() ではなく []）に従います。HTML テンプレートは有効なブロックマークアップを使用します。JSON は theme.json v3 スキーマに従います。

使用時機

以下の場合に使用してください：

• ブロックテーマコードレビュー（theme.json、HTML テンプレート、テンプレートパーツ）
• theme.json v3 スキーマ検証と構造チェック
• テンプレート階層監査（.html ファイル付きブロックテーマ、.php ファイル付きクラシックテーマ）
• テンプレートパーツレビュー（parts/header.html、parts/footer.html、parts/sidebar.html）
• グローバルスタイル分析（カラーパレット、タイポグラフィ、スペーシング、レイアウト設定）
• スタイルバリエーション検証（styles/ ディレクトリの別の theme.json ファイル）
• テーマ内のブロックパターンレビュー（patterns/ ディレクトリの PHP ファイル）
• 子テーマの互換性チェック（ブロックまたはクラシック子テーマ）
• クラシック・ツー・ブロックテーマ移行評価
• WordPress.org テーマ送信準備状況（Theme Check コンプライアンス）
• ブロックテーマでのハードコードされたスタイル検出
• フルサイト配置の useRootPaddingAwareAlignments 検証

以下の場合は使用しないでください：

• ブロックエディタコンポーネントレビュー（wp-block-development を使用してください。React/JSX ブロック用）
• プラグインアーキテクチャ監査（wp-plugin-development を使用してください。プラグイン構造用）
• セキュリティのみの監査（wp-security-review を使用してください。包括的なセキュリティ用）
• パフォーマンスのみの監査（wp-performance-review を使用してください。パフォーマンス分析用）
• WooCommerce テーマ統合（利用可能な場合は wp-woocommerce-dev を使用してください）
• ビジュアルデザイン評価（このスキルはコードレビューのみで、UI/UX レビューではありません）

コードレビューワークフロー

体系的なテーマレビュー用に、以下の 7 ステップのワークフローに従います：

1. テーマタイプとコンテキストを識別（THM-01）

   • ブロックテーマ → templates/index.html + theme.json + style.css を持つ
   • クラシックテーマ → index.php + style.css + functions.php を持つ（templates/ ディレクトリなし）
   • ハイブリッドテーマ → index.php AND theme.json の両方を持つ（ブロックエディタサポート付きクラシック）
   • 子テーマ → style.css に「Template:」ヘッダーがあり、親テーマを指す
   • WordPress.org 送信 → より厳格な標準（Theme Check コンプライアンス必須）

   自動検出パターン：

   # ブロックテーマ検出
   [ -f templates/index.html ] && [ -f theme.json ] && echo "Block theme"
   
   # クラシックテーマ検出
   [ -f index.php ] && [ ! -d templates ] && echo "Classic theme"
   
   # ハイブリッドテーマ検出
   [ -f index.php ] && [ -f theme.json ] && [ ! -d templates ] && echo "Hybrid theme"
   
   # 子テーマ検出
   grep -q "^Template:" style.css && echo "Child theme"
   

2. theme.json スキーマを検証（THM-02、THM-03、THM-04、THM-05）

   • version フィールドは MUST 3（WP 6.6+）。v1 は CRITICAL（非推奨）、v2 は WARNING（アップグレード可能）としてフラグ
   • 必須セクション：settings、styles
   • settings 構造を検証：color、typography、spacing、layout、border、shadow
   • v3 の破壊的変更を確認：defaultFontSizes と defaultSpacingSizes はデフォルトで true（テーマがカスタムサイズを定義する場合は明示的に false に設定する必要があります）
   • templateParts 配列を検証：name、title、area（header/footer/uncategorized）
   • customTemplates 配列を検証：name、title、postTypes
   • $schema フィールドをチェック（INFO 欠落時、IDE オートコンプリート強化）
   • ルートパディング存在時に useRootPaddingAwareAlignments を検証

3. テンプレート階層をチェック（THM-06、THM-07）

   • ブロックテーマ：templates/index.html 必須、他はオプション（home.html、front-page.html、single.html、page.html、archive.html、404.html、search.html）
   • クラシックテーマ：index.php 必須、標準階層（header.php、footer.php、single.php、page.php、archive.php）
   • テンプレートファイルが正しいマークアップを使用していることを確認：ブロックテーマ用 HTML ブロックマークアップ、クラシックテーマ用 PHP テンプレートタグ
   • ブロックテンプレート内のハードコードされたスタイルをチェック（CRITICAL なアンチパターン）
   • テンプレート内のテンプレートパーツ参照を検証

4. テンプレートパーツをチェック（THM-08）

   • parts/ ディレクトリ構造：header.html、footer.html、sidebar.html
   • theme.json で登録された templateParts がファイルと一致することを検証
   • area 指定をチェック（header/footer/uncategorized）
   • テンプレートパーツ内のブロックマークアップを検証
   • <!-- wp:template-part --> ブロック経由のテンプレートパーツ使用を検証

5. CRITICAL/WARNING/INFO パターンをスキャン

   • CRITICAL： 必須ファイル欠落（ブロックテーマ用 templates/index.html、クラシックテーマ用 index.php、すべてのテーマ用 style.css）、無効な theme.json version/構造、style.css ヘッダーフィール欠落、テンプレート階層違反、ハードコードされたインラインスタイルを持つブロックテーマは theme.json の目的を無視
   • WARNING： theme.json v2（v3 にアップグレード推奨）、theme.json プリセットではなく style.css 内のハードコードされたカラー/フォント値、ルートパディング付き useRootPaddingAwareAlignments 欠落、ブロックパターンが優先される場所のクラシックパターン、ブロックテーマの非推奨 add_theme_support()
   • INFO： スタイルバリエーション欠落、add_theme_support() の代わりに theme.json を使用可能、フォントはローカルホスティング可能、カスタムテンプレート登録欠落

6. コンテキスト対応重大度調整を適用

   • ブロックテーマコンテキスト：ハードコードされたスタイル = WARNING、theme.json セクション欠落 = WARNING
   • クラシックテーマコンテキスト：移行機会 = INFO、theme.json 欠落 = INFO
   • ハイブリッドテーマコンテキスト：段階的採用ガイダンス、クラシックと theme.json パターンの両方を検証
   • 子テーマコンテキスト：親互換性、オーバーライド検証
   • WordPress.org コンテキスト：Theme Check の失敗 = CRITICAL

7. クロスリファレンス付きでレポート

   • FILE でグループ化（PHP、HTML、JSON はパス別に混在）
   • 行番号、重大度、BAD/GOOD ペアを含める
   • セキュリティ問題が見つかった場合（テンプレートエスケーピング）：「セキュリティ問題が検出されました。包括的なセキュリティ分析のために /wp-sec-review を実行してください。」
   • プラグインのようなパターンが見つかった場合（functions.php フック）：「プラグインアーキテクチャパターンが検出されました。プラグイン開発ガイダンス用に /wp-plugin-review を実行してください。」
   • ブロックマークアップ問題が見つかった場合：「ブロックマークアップの問題が検出されました。ブロック開発ガイダンス用に /wp-block-review を実行してください。」

ファイルタイプ別チェック

theme.json（THM-02、THM-03、THM-04、THM-05）

version フィールド：

• CRITICAL：version フィールド欠落 → テーマが正しく読み込まれません
• CRITICAL：version 1 → 非推奨、v3 にアップグレード必須
• WARNING：version 2 → v3 へのアップグレード推奨（defaultFontSizes と defaultSpacingSizes の破壊的変更）
• パターン："version": 3

$schema フィールド：

• INFO：$schema 欠落 → IDE で検証できません
• パターン："$schema": "https://schemas.wp.org/trunk/theme.json"

settings.color：

• WARNING：palette 欠落 → ユーザーがサイトエディタで色をカスタマイズできません
• WARNING：palette 定義なしのハードコードされたカラー 16 進数値
• パターン：slug、color、name を持つ color.palette 配列
• 利用可能なプロパティ：palette、gradients、duotone、custom、defaultPalette、link、heading、button、caption

settings.typography：

• WARNING：fontSizes 欠落 → ユーザーがフォントサイズをカスタマイズできません
• CRITICAL（v3）：テーマが fontSizes を定義していますが "defaultFontSizes": false 欠落 → WordPress デフォルトがテーマサイズをオーバーライド
• WARNING：Google Fonts CDN の代わりにローカルフォントファイルを使用（GDPR、パフォーマンス）
• パターン：typography.fontSizes 配列、ローカルフォント用 fontFace を持つ fontFamilies
• 利用可能なプロパティ：fontSizes、fontFamilies、fluid、lineHeight、fontWeight、letterSpacing、textDecoration、textTransform、defaultFontSizes

settings.spacing：

• WARNING：spacingSizes 欠落 → ユーザーがサイトエディタでスペーシングをカスタマイズできません
• CRITICAL（v3）：テーマが spacingSizes を定義していますが "defaultSpacingSizes": false 欠落 → WordPress デフォルトがテーマサイズをオーバーライド
• パターン：slug、size、name を持つ spacing.spacingSizes 配列
• 利用可能なプロパティ：spacingSizes、padding、margin、blockGap、units、customSpacingSize、spacingScale、defaultSpacingSizes

settings.layout：

• WARNING：contentSize と wideSize 欠落 → フルサイトブロックが正しく機能しない場合があります
• パターン："contentSize": "640px", "wideSize": "1200px"

settings.useRootPaddingAwareAlignments：

• WARNING：ルートレベルパディング付き useRootPaddingAwareAlignments 欠落 → フルサイトブロックがビューポート端に到達しません
• CRITICAL：useRootPaddingAwareAlignments true ですが padding が CSS ショートハンドを使用 → オブジェクト表記法を使用する必要があります
• パターン：styles.spacing.padding が存在する場合は true に設定

styles セクション：

• WARNING：CSS 変数の代わりのハードコードされた値 → theme.json の目的を無視
• パターン："#0073aa" ではなく var(--wp--preset--color--primary) を使用
• 利用可能なプロパティ：color、typography、spacing、border、shadow、elements、blocks

templateParts 配列：

• INFO：templateParts 登録欠落 → テンプレートパーツは機能しますが、UI に適切なラベルが表示されません
• パターン：name、title、area（header/footer/uncategorized）を持つ配列

customTemplates 配列：

• INFO：customTemplates 欠落 → ユーザーがエディタでカスタムテンプレートを選択できません
• パターン：name、title、postTypes を持つ配列

style.css（THM-09、THM-10）

必須ヘッダーフィール：

• CRITICAL：「Theme Name」欠落 → WordPress がテーマを認識しません
• WARNING：「Text Domain」欠落 → 国際化が機能しません
• WARNING：「Version」欠落 → アップデートが正しく機能しません
• INFO：「Requires at least」、「Tested up to」、「Requires PHP」欠落 → バージョン要件を強制できません
• WordPress.org 必須：Theme Name、Theme URI、Author、Author URI、Description、Version、Requires at least、Tested up to、Requires PHP、License、License URI、Text Domain

ブロックテーマスタイルパターン：

• WARNING：広範な CSS の代わりに theme.json を使用するブロックテーマ → FSE の目的を無視
• INFO：ハードコードされたカラー/フォント値を theme.json プリセットに移動可能
• パターン：ブロックテーマは最小限の style.css（メタデータ + クリティカル CSS のみ）を持つべき。スタイリングは theme.json から来ます

クラシックテーマスタイルパターン：

• INFO：クラシックテーマが theme.json を採用してブロックエディタをサポート（ハイブリッドアプローチ）

子テーマパターン：

• CRITICAL：子テーマが「Template:」ヘッダーを欠落 → 親から継承しません
• WARNING：子テーマテンプレートが親ディレクトリ名と一致しない → 親が見つかりません

ブロックテンプレート（templates/*.html）（THM-06、THM-11、THM-14）

必須テンプレート：

• CRITICAL：ブロックテーマに templates/index.html 欠落 → テーマが機能しません

テンプレートファイルの命名：

• INFO：特定のテンプレート（single.html、page.html、archive.html、404.html、search.html、home.html、front-page.html）を追加して、より優れた階層カバレッジを実現可能

ブロックマークアップ検証：

• CRITICAL：無効なブロックコメント構文 → テンプレートが解析されません
• WARNING：ハードコードされたインラインスタイル属性 → theme.json を無視し、ユーザーがカスタマイズできません
• WARNING：theme.json プリセットの代わりのハードコードされたカラー 16 進値
• WARNING：theme.json フルサイト タイポグラフィの代わりのハードコードされたピクセルフォントサイズ
• パターン：インラインスタイルではなく theme.json プリセット参照を持つブロック属性を使用

テンプレートパーツ使用：

• WARNING：テンプレートパーツ参照（ヘッダー/フッター）欠落 → ユーザーが標準構造を期待します
• パターン：<!-- wp:template-part {"slug":"header","area":"header"} /-->

useBlockProps 相当：

• INFO：ブロックテンプレートは動的ブロックのようなラッパー属性を必要としません（静的 HTML）

テンプレートパーツ（parts/*.html）（THM-08）

テンプレートパーツファイル：

• WARNING：theme.json で登録されたが templateParts ファイル欠落 → サイトエディタで 404
• WARNING：テンプレートパーツファイルが存在するが theme.json で登録されていない → UI に適切なラベル付きで表示されません
• パターン：parts/header.html、parts/footer.html、parts/sidebar.html

Area 指定：

• WARNING：theme.json と使用方法の間のテンプレートパーツ area 不一致 → 正しい場所にレンダリングされない場合があります
• 利用可能な area：header、footer、uncategorized（または WP 6.0+ のカスタム area）

ブロックマークアップ：

• ブロックテンプレートと同じ検証：ハードコードされたスタイルなし、theme.json プリセットを使用

functions.php（THM-12、THM-13）

ABSPATH チェック：

• WARNING：defined( 'ABSPATH' ) || exit; 欠落 → ダイレクトファイルアクセスが可能
• クロスリファレンス：wp-security-review でセキュリティの詳細を参照

ブロックテーマのセットアップ：

• WARNING：theme.json に含まれるべき add_theme_support() 呼び出し → 非推奨パターン
• ブロックテーマで許容可能な add_theme_support()：wp-block-styles、responsive-embeds、editor-styles（theme.json はこれらを置き換えることはできません）
• パターン：ほとんどの add_theme_support() 呼び出しは theme.json に移行

クラシックテーマのセットアップ：

• INFO：クラシックテーマがハイブリッドアプローチ用に add_theme_support() を theme.json に移行可能
• パターン：カラーパレット、フォントサイズ、行の高さ、スペーシング → theme.json settings

テーマフック：

• パターン：テーマセットアップ用 after_setup_theme、アセット用 wp_enqueue_scripts、カスタム投稿タイプ用 init
• クロスリファレンス：wp-plugin-development でフックシステムパターンを参照

アセット確認：

• WARNING：条件チェックなしですべてのページでアセットを確認 → パフォーマンス問題
• パターン：条件付きタグ（is_front_page、is_singular）または管理チェックを使用

ブロックパターン（patterns/*.php）（THM-15、THM-16）

パターンファイルヘッダ：

• CRITICAL：パターンファイルに Title または Slug ヘッダがない → 登録されません
• WARNING：パターン slug が名前空間化されていない（themename/pattern-slug） → 衝突のリスク
• パターン：Title、Slug、Categories、Description、Keywords、Block Types、Viewport Width を含むコメントブロック付き PHP ファイル

パターンファイル構造：

• WARNING：PHP タグなしのパターンファイル → 動的値を処理しません
• パターン：動的値用 <?php ?> タグ、その後ブロックマークアップ

パターン内のブロックマークアップ：

• テンプレートと同じ検証：theme.json プリセットを使用、ハードコードされたスタイルなし
• 動的値用 PHP 関数を使用：get_theme_file_uri()、esc_url()、esc_html()、翻訳関数

パターン登録：

• INFO：patterns/ ディレクトリのパターンは自動登録、手動 register_block_pattern() は不要（テーマのみ、プラグインではない）

スタイルバリエーション（styles/*.json）（THM-17、THM-18、THM-19）

バリエーションファイル構造：

• WARNING：バリエーション version フィール欠落 → 正しく読み込まれない場合があります
• WARNING：バリエーション title 欠落 → UI にファイル名が表示されます
• パターン：version、title、settings、styles を持つ JSON ファイル

バリエーション命名：

• INFO：バリエーションファイル名がバリエーション slug になります（dark.json → 「dark」）、title がディスプレイ名をオーバーライド
• パターン：わかりやすいファイル名を使用（dark.json、minimal.json、high-contrast.json）

バリエーションスキーマ：

• WARNING：無効な theme.json 構造を持つバリエーション → 適用されません
• パターン：theme.json と同じスキーマ（settings、styles セクション）、version はメインの theme.json と一致する必要があります

子テーマ（THM-20）

子テーマ検出：

• パターン：「Template:」ヘッダを持つ style.css

テンプレートオーバーライド：

• WARNING：子ブロックテーマ parts/header.html が親をオーバーライドしない → ファイル名はちょうど一致する必要があります
• WARNING：子 theme.json が親 templateParts をオーバーライドしない → parentParts 配列をコピーして変更する必要があります
• パターン：子テーマファイルはちょうど一致するファイル名で親をオーバーライド

子テーマ互換性：

• WARNING：変更される可能性があります親テンプレートパーツに依存する子テーマ → 脆いオーバーライド
• INFO：子テーマが unregister_block_pattern() を使用して親パターンを削除する可能性あります

クイック検出用検索パターン（THM-21）

これらの rg コマンドと shell チェックを使用して、テーマを素早くスキャンします。重大度別に整理されています。PHP、HTML テンプレート、JSON ファイルをカバーします。

CRITICAL パターン

# ブロックテーマに必須ファイルがない
[ ! -f templates/index.html ] && [ -f theme.json ] && echo "CRITICAL: Block theme missing templates/index.html"
[ ! -f theme.json ] && [ -d templates ] && echo "CRITICAL: templates/ exists but theme.json missing"

# クラシックテーマに必須ファイルがない
[ ! -f index.php ] && [ ! -d templates ] && echo "CRITICAL: Classic theme missing index.php"

# 無効または欠落バージョン付き theme.json
test -f theme.json && ! rg -q "\"version\"" theme.json && echo "CRITICAL: theme.json missing version"
rg -n "\"version\": 1" theme.json  # 非推奨
rg -n "\"version\": [^23]" theme.json  # 無効バージョン

# 欠落した style.css 必須ヘッダ
test -f style.css && ! rg -q "Theme Name:" style.css && echo "CRITICAL: style.css missing Theme Name header"

# カスタム fontSizes 付き v3 theme.json ですが defaultFontSizes: false がない
rg -n "\"fontSizes\"" theme.json
# 手動フォローアップ：カスタム fontSizes が定義されている場合、defaultFontSizes が明示的に false であることを確認してください。

# カスタム spacingSizes 付き v3 theme.json ですが defaultSpacingSizes: false がない
rg -n "\"spacingSizes\"" theme.json
# 手動フォローアップ：カスタム spacingSizes が定義されている場合、defaultSpacingSizes が明示的に false であることを確認してください。

# 子テーマ Template ヘッダがない
test -f style.css && ! rg -q "Template:" style.css && echo "CRITICAL: If this is a child theme, style.css is missing Template header"

WARNING パターン

# theme.json version 2（v3 にアップグレード推奨）
rg -n "\"version\": 2" theme.json

# ブロックテンプレートのハードコードされたインラインスタイル
rg -n "style=\"" templates/ parts/ -g '*.html'

# テンプレートのハードコードされたカラー 16 進値
rg -n "#[0-9a-fA-F]{6}" templates/ parts/ -g '*.html'

# テンプレートのハードコードされたピクセルフォントサイズ
rg -n "font-size:\s*[0-9]+px" templates/ parts/ -g '*.html'

# CSS shorthand パディング（機能しません）
rg -n "\"padding\":\s*\"" theme.json

# ブロックテーマに theme.json にあるべき add_theme_support()
rg -n "add_theme_support.*editor-color-palette" functions.php
rg -n "add_theme_support.*editor-font-sizes" functions.php
rg -n "add_theme_support.*custom-line-height" functions.php
rg -n "add_theme_support.*custom-spacing" functions.php

# functions.php の ABSPATH チェック欠落
test -f functions.php && ! sed -n '1,10p' functions.php | rg -q "defined.*ABSPATH" && echo "WARNING: functions.php missing ABSPATH check in first 10 lines"

# 必須ヘッダのないパターンファイル
rg -L "Title:" patterns -g '*.php'
rg -L "Slug:" patterns -g '*.php'

INFO パターン

# theme.json に $schema がない
test -f theme.json && ! rg -q "\"\\$schema\"" theme.json && echo "INFO: theme.json missing \$schema"

# スタイルバリエーション ディレクトリがない
[ ! -d styles ] && echo "INFO: Could add style variations in styles/"

# ブロックパターン ディレクトリがない
[ ! -d patterns ] && echo "INFO: Could add block patterns in patterns/"

# theme.json に templateParts 登録がない
test -f theme.json && ! rg -q "\"templateParts\"" theme.json && echo "INFO: theme.json missing templateParts registration"

# theme.json に customTemplates 登録がない
test -f theme.json && ! rg -q "\"customTemplates\"" theme.json && echo "INFO: theme.json missing customTemplates registration"

# Google Fonts CDN 使用（ローカルフォントを使用可能）
rg -n "fonts.googleapis.com" .

# theme.json のないクラシックテーマ（ハイブリッドは可能）
[ -f index.php ] && [ ! -f theme.json ] && echo "INFO: Classic theme could add theme.json for block editor support"

注記： HTML テンプレートパターンは PHP とは異なるもありが必要です。テンプレートには --include="*.html" を、PHP ファイルには --include="*.php" を、theme.json とバリエーションには --include="*.json" を使用してください。

テーマコンテキスト検出

検出されたテーマタイプに基づいたコンテキスト対応レビュー注記：

ブロックテーマ

構造： templates/index.html + theme.json + style.css、オプション parts/、patterns/、styles/ レビュー焦点：

• theme.json v3 検証が主な関心事
• テンプレートのハードコードされたスタイル = WARNING（FSE の目的を無視）
• テンプレート階層の完全性
• パディング存在時の useRootPaddingAwareAlignments
• 強化機会としてのスタイルバリエーションとパターン 共通の間違い： useRootPaddingAwareAlignments 欠落、ハードコードされたインラインスタイル、v3 への移行なし theme.json v2

クラシックテーマ

構造： index.php + style.css + functions.php、header.php、footer.php、テンプレートファイル レビュー焦点：

• テンプレートエスケーピング（wp-security-review をクロスリファレンス）
• クラシックテンプレート階層
• ブロックテーマまたはハイブリッドアプローチへの移行機会
• ブロックエディタサポート用 theme.json 採用を提案 共通の間違い： エスケーピング欠落、非推奨テンプレートタグ、モダンエディタ機能用 theme.json なし

ハイブリッドテーマ

構造： index.php + theme.json + functions.php（theme.json 付きクラシックテンプレート） レビュー焦点：

• クラシック and theme.json パターンの両方を検証
• クラシックテンプレートで CSS 変数使用を確認
• theme.json がブロックコンテンツに適用されることを確認
• ブロックテンプレートへの段階的移行を提案 共通の間違い： theme.json の設定が PHP テンプレート出力に影響しない、theme.json が PHP テンプレートのスタイリングを期待

子テーマ（ブロックまたはクラシック）

構造： 「Template:」ヘッダを持つ style.css、オプションテンプレートオーバーライド レビュー焦点：

• 親互換性（テンプレートファイル名はちょうど一致する必要があります）
• theme.json オーバーライドパターン（子は親 templateParts をコピー + 変更する必要があります）
• テンプレートパーツオーバーライド
• unregister_block_pattern() でパターン削除 共通の間違い： テンプレートパーツが親をオーバーライドしない（ファイル名間違い）、theme.json が親設定をオーバーライドしない

WordPress.org テーマ送信

構造： 任意のテーマタイプですが、より厳格な標準 レビュー焦点：

• Theme Check プラグインコンプライアンス（すべてのエラー = CRITICAL）
• 必須ファイル：完全なヘッダを持つ style.css、readme.txt、screenshot.png
• ライセンス互換性（GPL または GPL 互換）
• 難読化コードなし、フォームなし、フリーテーマの販促なし
• すべての関数/クラスに接頭辞を付けます 共通の間違い： readme.txt 欠落、不完全な style.css ヘッダ、Theme Check エラー

クイックリファレンス：テーマ開発パターン（THM-22、THM-23）

懸念別に整理された一般的なテーマパターン。PHP の例は WordPress PHP コーディング標準を使用（括弧内のスペース、array() ではなく []、Yoda 条件）。HTML テンプレートは有効なブロックマークアップを使用します。JSON の例は有効な theme.json v3 構文を使用します。

theme.json v3 完全な構造

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"useRootPaddingAwareAlignments": true,
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				},
				{
					"slug": "secondary",
					"color": "#005177",
					"name": "Secondary"
				},
				{
					"slug": "foreground",
					"color": "#333333",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#ffffff",
					"name": "Background"
				}
			]
		},
		"typography": {
			"defaultFontSizes": false,
			"fluid": true,
			"fontFamilies": [
				{
					"fontFamily": "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
					"name": "Inter",
					"slug": "inter",
					"fontFace": [
						{
							"fontFamily": "Inter",
							"fontWeight": "400",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-regular.woff2" ]
						},
						{
							"fontFamily": "Inter",
							"fontWeight": "700",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-bold.woff2" ]
						}
					]
				}
			],
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				},
				{
					"slug": "medium",
					"size": "1rem",
					"name": "Medium"
				},
				{
					"slug": "large",
					"size": "1.5rem",
					"name": "Large"
				}
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{
					"slug": "30",
					"size": "1rem",
					"name": "Small"
				},
				{
					"slug": "40",
					"size": "1.5rem",
					"name": "Medium"
				},
				{
					"slug": "50",
					"size": "2rem",
					"name": "Large"
				}
			],
			"units": [ "px", "rem", "vh", "vw", "%" ]
		},
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"border": {
			"radius": true,
			"color": true,
			"style": true,
			"width": true
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		},
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--inter)",
			"fontSize": "var(--wp--preset--font-size--medium)",
			"lineHeight": "1.6"
		},
		"spacing": {
			"padding": {
				"top": "var(--wp--preset--spacing--50)",
				"right": "var(--wp--preset--spacing--50)",
				"bottom": "var(--wp--preset--spacing--50)",
				"left": "var(--wp--preset--spacing--50)"
			}
		},
		"elements": {
			"link": {
				"color": {
					"text": "var(--wp--preset--color--primary)"
				}
			},
			"heading": {
				"typography": {
					"fontWeight": "700",
					"lineHeight": "1.2"
				}
			}
		},
		"blocks": {
			"core/button": {
				"color": {
					"background": "var(--wp--preset--color--primary)",
					"text": "var(--wp--preset--color--background)"
				}
			}
		}
	},
	"customTemplates": [
		{
			"name": "page-no-title",
			"title": "Page Without Title",
			"postTypes": [ "page" ]
		}
	],
	"templateParts": [
		{
			"name": "header",
			"title": "Header",
			"area": "header"
		},
		{
			"name": "footer",
			"title": "Footer",
			"area": "footer"
		}
	]
}

ブロックテンプレート構造（templates/single.html）

❌ BAD：ハードコードされたインラインスタイルは theme.json を無視します

<!-- wp:template-part {"slug":"header"} /-->

<main style="max-width: 1200px; margin: 0 auto; padding: 2rem; color: #333;">
	<h1 style="font-size: 32px; color: #0073aa;">Post Title</h1>
	<div style="font-size: 16px; line-height: 1.6;">
		<!-- wp:post-content /-->
	</div>
</main>

<!-- wp:template-part {"slug":"footer"} /-->

✅ GOOD：ブロック属性と theme.json プリセットを使用します

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:post-title {"level":1} /-->

	<!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap"}} -->
	<div class="wp-block-group">
		<!-- wp:post-author {"showAvatar":true} /-->
		<!-- wp:post-date /-->
	</div>
	<!-- /wp:group -->

	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

テンプレートパーツ構造（parts/header.html）

❌ BAD：ハードコードされたカラーと間隔

<div style="background: #ffffff; padding: 20px; border-bottom: 1px solid #cccccc;">
	<div style="max-width: 1200px; margin: 0 auto; display: flex; justify-content: space-between;">
		<h1 style="font-size: 24px; color: #0073aa;">Site Title</h1>
		<nav>Navigation</nav>
	</div>
</div>

✅ GOOD：theme.json プリセット参照付きブロック属性を使用します

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|40","bottom":"var:preset|spacing|40"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
	<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"nowrap"}} -->
	<div class="wp-block-group">
		<!-- wp:site-logo {"width":60} /-->
		<!-- wp:site-title {"level":0} /-->

		<!-- wp:navigation {"layout":{"type":"flex","orientation":"horizontal"}} /-->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->

useRootPaddingAwareAlignments

❌ BAD：useRootPaddingAwareAlignments なしのルートパディング

{
	"version": 3,
	"styles": {
		"spacing": {
			"padding": {
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}

結果：フルサイトブロックの左右に白いスペース

❌ BAD：CSS shorthand パディング付き useRootPaddingAwareAlignments（機能しません）

{
	"version": 3,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": "2rem"
		}
	}
}

結果：機能しません、オブジェクト表記法を使用する必要があります

✅ GOOD：オブジェクト表記法付き useRootPaddingAwareAlignments

{
	"version": 3,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": {
				"top": "var(--wp--preset--spacing--50)",
				"right": "var(--wp--preset--spacing--50)",
				"bottom": "var(--wp--preset--spacing--50)",
				"left": "var(--wp--preset--spacing--50)"
			}
		}
	}
}

theme.json v2 から v3 への移行

❌ BAD：デフォルトを調整せずにバージョンをアップグレード

{
	"version": 3,
	"settings": {
		"typography": {
			"fontSizes": [
				{ "slug": "small", "size": "14px" },
				{ "slug": "medium", "size": "16px" }
			]
		}
	}
}

結果：WordPress のデフォルトフォントサイズも表示されます。テーマのサイズはオーバーライドしません

✅ GOOD：明示的な defaultFontSizes: false を持つ v3

{
	"version": 3,
	"settings": {
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "medium", "size": "1rem", "name": "Medium" }
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{ "slug": "30", "size": "1rem", "name": "Small" }
			]
		}
	}
}

テーマ内のブロックパターン（patterns/hero.php）

❌ BAD：必須ヘッダのないパターン

<?php
// Title と Slug ヘッダがない
?>
<!-- wp:cover -->
<div class="wp-block-cover">
	<h1>Welcome</h1>
</div>
<!-- /wp:cover -->

✅ GOOD：ヘッダと動的値を持つ完全なパターン

<?php
/**
 * Title: Hero Section
 * Slug: mytheme/hero
 * Categories: featured, banner
 * Keywords: hero, banner, header
 * Block Types: core/cover
 * Viewport Width: 1400
 * Description: Full-width hero section with heading and CTA
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero.jpg' ) ); ?>","dimRatio":50,"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
	<img class="wp-block-cover__image-background" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero.jpg' ) ); ?>" data-object-fit="cover" />

	<div class="wp-block-cover__inner-container">
		<!-- wp:heading {"textAlign":"center","level":1} -->
		<h1 class="has-text-align-center"><?php echo esc_html_x( 'Welcome to Our Site', 'Pattern placeholder', 'mytheme' ); ?></h1>
		<!-- /wp:heading -->

		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button -->
			<div class="wp-block-button">
				<a class="wp-block-button__link wp-element-button"><?php echo esc_html_x( 'Get Started', 'Pattern placeholder', 'mytheme' ); ?></a>
			</div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->

スタイルバリエーション（styles/dark.json）

❌ BAD：バージョンまたはタイトル欠落のバリエーション

{
	"settings": {
		"color": {
			"palette": [
				{ "slug": "background", "color": "#1a1a1a" }
			]
		}
	}
}

✅ GOOD：バージョンとタイトル付き完全なバリエーション

{
	"version": 3,
	"title": "Dark Mode",
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "foreground",
					"color": "#ffffff",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#1a1a1a",
					"name": "Background"
				},
				{
					"slug": "primary",
					"color": "#3dadff",
					"name": "Primary"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		}
	}
}

ブロックテーマ用 functions.php

❌ BAD：theme.json の代わりに add_theme_support() を使用

<?php
function mytheme_setup() {
	add_theme_support( 'align-wide' );
	add_theme_support( 'custom-line-height' );
	add_theme_support( 'custom-spacing' );
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => 'Primary',
			'slug'  => 'primary',
			'color' => '#0073aa',
		),
	) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

✅ GOOD：最小限の functions.php、theme.json の設定

<?php
/**
 * Theme setup and initialization
 */

defined( 'ABSPATH' ) || exit;

/**
 * Theme setup
 */
function mytheme_setup() {
	// Still valid in block themes
	add_theme_support( 'wp-block-styles' );
	add_theme_support( 'responsive-embeds' );
	add_theme_support( 'editor-styles' );

	// Load editor stylesheet
	add_editor_style( 'style.css' );

	// Internationalization
	load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

/**
 * Enqueue additional scripts (if needed)
 */
function mytheme_enqueue_assets() {
	// Only if theme needs custom JS
	if ( is_front_page() ) {
		wp_enqueue_script(
			'mytheme-interactions',
			get_theme_file_uri( '/assets/js/interactions.js' ),
			array(),
			wp_get_theme()->get( 'Version' ),
			true
		);
	}
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

クラシック・ツー・ブロック・テーマ移行

❌ BAD：クラシックアプローチ（ブロックテーマでは非推奨）

<?php
// functions.php in classic theme
function classictheme_setup() {
	add_theme_support( 'custom-logo' );
	add_theme_support( 'custom-header' );
	add_theme_support( 'custom-background' );
	add_theme_support( 'editor-color-palette', array(
		array( 'name' => 'Primary', 'slug' => 'primary', 'color' => '#0073aa' ),
	) );
	add_theme_support( 'editor-font-sizes', array(
		array( 'name' => 'Small', 'size' => 14, 'slug' => 'small' ),
	) );
}
add_action( 'after_setup_theme', 'classictheme_setup' );

✅ GOOD：theme.json 経由のブロックテーマアプローチ

{
	"version": 3,
	"settings": {
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				}
			]
		},
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				}
			]
		}
	}
}

子テーマパターン

❌ BAD：Template ヘッダのない子テーマ style.css

/*
Theme Name: My Child Theme
Description: A child theme
Author: Author Name
*/

結果：WordPress が親テーマを認識しません

✅ GOOD：完全な子テーマ style.css

/*
Theme Name: My Child Theme
Template: parent-theme-folder
Description: A child theme extending Parent Theme
Author: Author Name
Author URI: https://example.com
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-child-theme
*/

子テーマテンプレートパーツオーバーライド：

parent-theme/
├── parts/
│   └── header.html

child-theme/
├── style.css (Template: parent-theme 付き)
└── parts/
    └── header.html  ← オーバーライドするにはファイル名がちょうど一致する必要があります

重大度の定義（THM-23）

重大度	定義	例
CRITICAL	テーマが機能しない OR WordPress.org 拒否	必須ファイル欠落（ブロックテーマ用 templates/index.html、クラシックテーマ用 index.php、すべてのテーマ用 style.css）、無効な theme.json version（v1 非推奨）、style.css 「Theme Name」ヘッダ欠落、テンプレート階層違反、子テーマ 「Template:」ヘッダ欠落、カスタム fontSizes/spacingSizes を持つ theme.json v3 ですが defaultFontSizes/defaultSpacingSizes: false 欠落（WordPress デフォルトはテーマをオーバーライド）、CSS shorthand パディング付き useRootPaddingAwareAlignments（オブジェクト表記法を使用する必要があります）、Title または Slug ヘッダのないパターンファイル
WARNING	テーマは機能しますが、品質/互換性の問題があります	theme.json v2（v3 の破壊的変更用にアップグレード推奨）、ブロックテーマテンプレートのハードコードされたスタイル（インラインスタイル属性、ハードコードされた 16 進カラー、ピクセルフォントサイズ）、ルートパディング付き useRootPaddingAwareAlignments 欠落（フルサイトブロックが端に到達しません）、ブロックパターンが優先される場所のクラシックパターン、ブロックテーマの非推奨 add_theme_support() 呼び出し（editor-color-palette、editor-font-sizes、custom-line-height、custom-spacing は theme.json にあるべき）、functions.php の ABSPATH チェック欠落、theme.json 登録なしのテンプレートパーツファイル、ハードコードされた WordPress パス（/wp-content/themes/）
INFO	ベストプラクティスの改善 OR 最適化機会	theme.json に $schema 欠落（IDE 検証）、スタイルバリエーション ディレクトリ欠落、ブロックパターン ディレクトリ欠落、templateParts または customTemplates 登録欠落、Google Fonts CDN ローカルフォントの代わりに（GDPR、パフォーマンス）、theme.json のないクラシックテーマ（ハイブリッドは可能）、より優れた階層用に特定のテンプレート（single.html、page.html）を追加可能、子テーマが unregister_block_pattern() で親パターンを削除可能、style.css の