wp-patterns

WordPress ブロックパターン

必要な入力情報

• リポジトリのルートと対象のテーマ／プラグインディレクトリ。
• パターンの種類：セクション、スターターページ、テンプレート、テンプレートパーツ、または手動登録するプラグインパターン。
• テーマ／プラグインのスラッグ、パターンのスラッグ、テキストドメイン。
• パターンのタイトル、カテゴリー、キーワード、ブロックタイプ、テンプレートタイプ、インサーターでの表示設定。
• このリポジトリの互換性契約と異なる場合は、対象の WordPress バージョン。
• 色、タイポグラフィ、余白、レイアウト、グラデーションに利用できる theme.json のプリセット。
• 画像／アイコンのアセットパス。アセットが装飾用か情報提供用かも含めます。
• 検証環境：WordPress Playground、wp-env、ローカルの WordPress、またはコードエディターでの手動確認。
• 既存のパターンを更新する場合：現在のスラッグ、現在のファイルパス、既存の挿入済みコンテンツとの互換性を維持する必要があるかどうか。
• 子テーマの場合：子テーマのスラッグ、テキストドメイン、アセットルート。明示的な意図がない限り、親テーマの名前空間を再利用しないでください。

ガードレール

1. ブロックマークアップのみ — すべてのビジュアルデザインは、ブロックコメントの属性と preset スラッグで表現します。インラインの <style> タグ、カスタム CSS クラス、ブロックのラッパー外の任意の HTML は使用しません。基本原則については references/design-with-tokens.md を参照してください。

2. JavaScript は使用しない — パターンは静的な block markup です。インタラクティブ機能には、標準で対応しているブロック（Navigation、Search、Query Loop）を使用します。

3. 登録時の PHP — パターンファイル内の PHP は、レンダリング時ではなく登録時に一度だけ実行されます。安全な出力関数、i18n、避けるべき関数については references/pattern-registration.md を参照してください。

4. 有効なネスト — コメント構文とネスト規則については references/block-markup-reference.md を参照してください。

5. 動作には標準ブロックを使用 — カスタム PHP／HTML で動作を実装する代わりに、Query Loop、Search、Navigation、Social Icons、または既存のフォームブロックを使用します。ニュースレター、寄付、決済、地図の機能には、CTA／プレースホルダーを作成するか、既存のブロック／プラグインを使用します。

6. ローカルアセット — get_theme_file_uri() と esc_url() を使用します。ユーザーの承認がない限り、外部のプレースホルダー URL は使用しません。例については references/pattern-registration.md と references/anti-patterns.md を参照してください。

手順

0) トリアージを行い、パターンの配置先を特定する

1. リポジトリで作業する場合は、トリアージを実行します。
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. ブロックテーマの場合は、対象テーマのルートを特定します。
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs
3. パターンをテーマの patterns/ ディレクトリに配置するか、プラグインで手動登録する必要があるか確認します。
4. 複数のテーマ／プラグインがある場合は、すべての変更を指定された対象に限定します。

必要な入力情報がユーザーから提供されていない場合は、リスクの低いデフォルトのみを推定します。テーマのスラッグ、テキストドメイン、アセットパス、カスタム投稿タイプ、タクソノミー、イベント日付フィールド、テーマ固有の preset を新たに決める前に、ユーザーに確認してください。theme.json が見つからない場合やプリセットを検証できない場合は、無難なコアプリセットを使用するか、テーマ固有のスラッグを使う前に確認してください。

完了条件： 対象のテーマ／プラグインのルート、パターンの種類、登録先が確定していること。

1) デザインの検討

block markup を記述する前に、目的、トーン、空間構成、タイポグラフィの階層、色の方針という5つのデザイン上の判断を慎重に行います。

判断の枠組みと preset の対応付けについては references/design-with-tokens.md を参照してください。

パターンの種類に応じたメタデータ（スターターページ、テンプレートパターン、テンプレートパーツ、クエリループ、フォーム／CTA、比較／料金、ソーシャル／ナビゲーション／検索、404）については、core/query を使う場合の Query Loop パターンのセクションを含め、references/pattern-categories-and-types.md を参照してください。

視覚的に 際立つ 構成が求められている場合は、references/visual-composition.md を参照してください。

完了条件： マークアップを作成する前に、5つのデザイン上の判断をすべて行い、記録していること。

2) ブロック構造を計画する

マークアップを書く前に、ネスト構造のツリーをスケッチします。ヒーローパターンの例：

Group (full-width, constrained layout, dark bg, vertical padding 80)
  Group (constrained inner, flex vertical, center align)
    Paragraph (uppercase label, small, letter-spacing, accent color)
    Heading (h2, xx-large, heading font, tight line-height)
    Paragraph (lead text, large, secondary color)
    Buttons (flex, center)
      Button (primary bg, base text)
      Button (outline style)

完了条件： コメントタグを書く前に、ネスト構造のツリーをスケッチし、意図的に階層を設計していること。

3) パターンファイルを書く

PHP ヘッダーとblock markupを組み立てます。ヘッダーのフィールド、PHP のルール、手動登録、ファイルの例については、references/pattern-registration.mdを参照してください。

手順 1 で選んだカテゴリーとテンプレートタイプを使用します。手順 1 でヘッダーのメタデータを決めていない場合は、references/pattern-categories-and-types.mdを参照してください。

ブロックマークアップ本文：

• 手順 2 のネスト構造ツリーに従います
• 色、フォントサイズ、間隔にはpresetのスラッグを使用します
• 実際のコンテンツを反映したプレースホルダーテキストを使用します。「Lorem ipsum」は使用しません

完了条件： PHP ヘッダーとブロックマークアップのファイルが書かれていること。

4) デザイン品質を確認する

references/anti-patterns.mdのデザイン品質チェックリストに照らして確認します。すべての項目に合格する必要があります。

完了条件： デザイン品質チェックリストのすべての項目に合格していること。

5) 技術的な検証

references/anti-patterns.mdの技術検証チェックリストに照らして確認します。すべての項目に合格する必要があります。

完了条件： 技術検証チェックリストのすべての項目に合格していること。

検証

実際の WordPress 環境でパターンをテストします。

WordPress Playground を使用する場合（推奨）：

npx @wp-playground/cli@latest server --auto-mount

テーマディレクトリをマウントして、次の点を確認します。

• 指定したカテゴリーの下にあるインサーターにパターンが表示される
• ブロックの検証エラーなしでパターンを挿入できる
• デスクトップとモバイルの画面幅でレイアウトが正しく表示される
• コンテンツ（テキスト、画像、ボタン）を編集できる
• templateLockを使用している場合、ロックされた要素を編集できない

テンプレートパターンの場合は、サイトエディターで想定どおりのテンプレート置換フローにパターンが表示されることを確認します。Inserter: noを使用している場合は、一般のインサーターには表示されず、意図した場所では引き続き利用できることを確認します。

手動確認：

• WordPress のコードエディター表示にブロックマークアップを貼り付けます
• ビジュアルエディターに切り替えます。ブロックが「Attempt Block Recovery」のプロンプトなしで解析される必要があります
• 復旧が必要な場合、マークアップに構文エラーがあります

パターンの変更がアセット、生成ファイル、または登録コードに影響する場合は、リポジトリに既存の lint、ビルド、またはテストコマンドを実行します。

既存のパターンを更新する場合、挿入されたパターンのコンテンツは投稿やテンプレートにコピーされることに注意してください。パターンファイルを変更しても、すでに挿入されたコンテンツは遡って更新されません。また、ブロック名や保存済みマークアップを変更すると、新たに挿入されたコンテンツに復旧プロンプトが表示されることがあります。

PR またはパッケージのレビューでは、差分が対象のパターンファイル、参照資料、スクリプト、評価シナリオに限定されていることを確認します。パターンの変更に無関係なリポジトリの更新を混在させないでください。

失敗時の対処／デバッグ

まず、references/block-markup-reference.md、references/pattern-registration.md、references/anti-patterns.mdを確認してください。

よくある問題：

• インサーターにパターンが表示されない：Title、Slug、Categoriesの必須ヘッダーを確認してください。ファイルがpatterns/*.phpの下にあることと、Inserter: noによって非表示になっていないことも確認してください。
• 誤ったパターンが表示される、または上書きされる：スラッグの重複を確認し、theme-slug/pattern-nameまたはplugin-slug/pattern-nameの形式で名前空間を付けてください。
• ブロックのリカバリープロンプトが表示される：ブロックコメントのネスト、JSON構文、閉じコメントを検証してください。
• 文字列が翻訳されない、またはエスケープされない：状況に応じて、未加工のテキスト／PHP出力をesc_html_e()、esc_html__()、esc_attr_e()、esc_attr__()、またはesc_url()に置き換えてください。
• 翻訳が読み込まれない：テキストドメインが対象のテーマ／プラグインと一致していることを確認してください。
• 動的コンテンツが古い、または利用できない：クエリー依存のPHP（get_posts()、the_title()、wp_get_current_user()）を削除し、代わりにクエリーループなどのブロックを使用してください。
• クエリーループの出力が不完全：必要に応じて、core/post-template、投稿タイトル／抜粋／日付／画像ブロック、ページネーション、core/query-no-resultsのフォールバックを確認してください。
• アーカイブ／検索／カテゴリー／投稿者のコンテキストが誤っている：ハードコードした実行時PHPではなく、継承されたクエリーコンテキストを使用してください。
• CPTまたはイベント一覧が誤っている：パターンを生成する前に、投稿タイプのスラッグ、タクソノミー／日付フィールド、プラグインが提供するブロックを確認してください。
• スタイルがテーマと一致しない：presetスラッグがtheme.jsonに存在することを確認してください。ドキュメントに記載されていないテーマ固有のスラッグは使用しないでください。
• アクセシビリティの問題：見出しレベルの飛ばし、情報を伝える画像の空の代替テキスト、コントラストの低いプリセットの組み合わせ、曖昧なボタン／リンクテキスト、ソーシャルアイコンのラベル、検索ラベル、色だけによる強調を修正してください。
• 手動登録に失敗する：コードがinitで実行されること、カテゴリーがパターンより先に登録されること、パターンのコンテンツが静的なブロックマークアップのままであることを確認してください。

エスカレーション

次の場合は作業を中止し、支援を求めるか、正式なドキュメントを参照してください。

• テーマ固有のpresetスラッグ、テキストドメイン、アセットパス、パターンカテゴリーを検証できない場合。
• 色のコントラスト、画像の意味、コンテンツの階層について、人によるデザイン／アクセシビリティ上の判断が必要な場合。
• このリポジトリの互換性契約で対象としていないWordPress／Gutenbergのバージョンに動作が依存する場合。

プロンプトの例

references/example-prompts.mdを確認してください。