wp-block-themes

WP ブロックテーマ

使用する場面

次のようなブロックテーマの作業で、このスキルを使用します。

• theme.json の編集（プリセット、設定、スタイル、ブロックごとのスタイル）
• テンプレート（templates/*.html）とテンプレートパーツ（parts/*.html）の追加や変更
• パターン（patterns/*.php）の追加と、インサーターに表示される内容の制御
• スタイルバリエーション（styles/*.json）の追加
• 「スタイルが適用されない」「エディターに theme.json の変更が反映されない」問題のデバッグ

必要な入力

• リポジトリのルートと、対象のテーマ（複数ある場合はテーマディレクトリ）。
• 対象とする WordPress のバージョン範囲（theme.json のバージョンや機能はコアのバージョンによって異なります）。
• 問題が発生する場所：サイトエディター、投稿エディター、フロントエンド、またはすべて。

手順

0) ブロックテーマのルートを調査して特定する

1. 調査を実行します。
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. テーマのルートと主要フォルダーを特定します。
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

テーマが複数ある場合は、1 つを選び、すべての変更をそのテーマのルート内に限定します。

1) 新しいブロックテーマを作成する（必要な場合）

新しいブロックテーマを一から作成する（またはクラシックテーマを変換する）場合：

• ファイル構成を推測するのではなく、実績のあるひな形から始める（または WP 環境からエクスポートする）ことを推奨します。
• theme.json のスキーマバージョンは異なるため、サポートする WordPress の最低バージョンを明示します。

参照：

• references/creating-new-block-theme.md

テーマのルートを作成したら、detect_block_themes を再実行し、以下の手順に進みます。

2) テーマの種類と上書きの挙動を確認する

• ブロックテーマを示す要素：
  • theme.json が存在する
  • templates/ および／または parts/ が存在する
• スタイルの優先順位を確認します。
  • コアのデフォルト → theme.json → 子テーマ → ユーザーのカスタマイズ
  • ユーザーのカスタマイズによって、theme.json の変更が「無視」されているように見えることがあります

参照：

• references/debugging.md（スタイルの優先順位と最速の確認方法）

3) theme.json を安全に変更する

何を変更するかを決めます。

• 設定（UI でできること）：プリセット、タイポグラフィのスケール、色、レイアウト、間隔
• スタイル（デフォルトの見た目）：要素やブロックに対する CSS のようなルール

参照：

• references/theme-json.md

4) テンプレートとテンプレートパーツ

• テンプレートは templates/ にあり、HTML 形式です。
• テンプレートパーツは parts/ にあり、サブディレクトリにネストしてはいけません。

参照：

• references/templates-and-parts.md

5) パターン

テーマが所有するパターンが必要な場合は、patterns/ 内のファイルシステムパターンを推奨します。

参照：

• references/patterns.md

6) スタイルバリエーション

スタイルバリエーションは styles/ 内の JSON ファイルです。注：ユーザーがスタイルバリエーションを選択すると、その選択は DB に保存されるため、ファイルを変更しても「ユーザーに表示される内容」が自動的に更新されないことがあります。

参照：

• references/style-variations.md

検証

• 期待どおりの場所（スタイル UI、テンプレート、パターン）に変更がサイトエディターで反映されている。
• フロントエンドが期待どおりのスタイルで表示される。
• スタイルが変わらない場合は、ユーザーのカスタマイズがテーマのデフォルトを上書きしているかどうかを確認する。
• アセット（フォント、カスタム JS／CSS のビルド）が関係する場合は、リポジトリのビルド／lint スクリプトを実行する。

よくある失敗／デバッグ

まず、次を確認します。

• references/debugging.md

よくある問題：

• テーマのルートが間違っている（有効でないテーマを編集している）
• ユーザーのカスタマイズがデフォルトを上書きしている
• theme.json の構造や記述に誤りがあり、適用されない
• テンプレート／パーツのフォルダーが間違っている（またはパーツがネストされている）

エスカレーション

上流の挙動が不明確な場合は、公式ドキュメントを参照します。

• theme.json、テンプレート、パターン、スタイルバリエーションについては、Theme Handbook と Block Editor Handbook を参照してください。