wordpress-block-theming

WordPress ブロックテーマのスキル

Full Site Editing（FSE）アーキテクチャを使用して WordPress ブロックテーマを構築するための包括的な知識です。

絶対的なルール

• 絵文字禁止：生成するコンテンツでは、見出し、段落、ボタンのテキストなど、どこにも絵文字を使用しないでください。これは、すべてのテンプレート、パターン、コンテンツに適用されます。

テーマアーキテクチャ

ディレクトリ構造

theme-slug/
├── theme.json           # Central configuration file
├── style.css            # Theme metadata + custom CSS
├── functions.php        # Asset enqueuing, pattern registration
├── templates/           # Block templates
│   ├── index.html       # Main/fallback template
│   ├── single.html      # Single post
│   ├── page.html        # Single page
│   ├── archive.html     # Archive listings
│   ├── search.html      # Search results
│   └── 404.html         # Not found
├── parts/               # Reusable template parts
│   ├── header.html      # Site header
│   └── footer.html      # Site footer
└── patterns/            # Block patterns
    ├── hero.php
    ├── features.php
    └── cta.php

theme.json の設定

theme.json ファイルは、ブロックテーマの中心的な設定ファイルです。以下を定義します。

スキーマとバージョン

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

設定

エディターで使用できるオプションを定義します。

{
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "800px", "wideSize": "1280px" },
    "color": {
      "palette": [ /* 5 colors: primary, secondary, accent, light, dark */ ],
      "defaultPalette": false,
      "defaultGradients": false
    },
    "typography": {
      "fontFamilies": [ /* heading + body font families */ ],
      "fontSizes": [ /* 5-6 step scale: small through huge */ ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "%", "vw", "vh"],
      "spacingSizes": [ /* 6 steps from compact to spacious */ ]
    }
  }
}

スタイル

サイトとブロックのデフォルトスタイルを定義します。

{
  "styles": {
    "color": { /* background + text from palette */ },
    "typography": { /* body font family, medium size, line-height 1.5-1.65 */ },
    "elements": {
      "heading": { /* heading font family, appropriate weight, line-height 1.1-1.3 */ },
      "link": { /* accent color */ },
      "button": { /* accent background, light text, border-radius */ }
    }
  }
}

タイポグラフィ

• 美しく、独自性があり、印象的なフォントを選びます。Arial や Inter のような汎用的なフォントは避け、フロントエンドの美しさを高める、個性的で特徴のあるフォントを選びます。独特なディスプレイフォントと洗練された本文用フォントを組み合わせます。
• フォントサイズのスケール：実用的で使いやすいサイズにします。本文：1rem。見出し：控えめに拡大します（h1 は ≤ 2.5～3rem）。レスポンシブなディスプレイテキストには clamp() を使いますが、最大値は約 3.5rem にします。4rem を超える「巨大な」サイズは避けてください。デザインがよくなることはまれで、多くの場合、見栄えを損ないます。適切な 6 段階のスケール：0.875rem / 1rem / 1.25rem / 1.75rem / 2.25rem / clamp(2.5rem, 4vw, 3.5rem)。
• 行の高さ：本文：1.5～1.65。見出し：1.1～1.3。どのテキストでも 1.0 未満にしないでください。theme.json の styles.typography.lineHeight と styles.elements.heading.typography.lineHeight で設定します。

ブロックテンプレート

テンプレートでは WordPress のブロックマークアップ（JSON 属性を含む HTML コメント）を使用します。

テンプレートの構造

<main class="wp-block-group">
  
</main>

テンプレートパーツ

ヘッダーの要件

• サイトに適した背景を持つ、幅が制約されたレイアウトグループ
• フレックス行：site-title（レベル：0 — <p> として出力され、<h1> にはなりません）＋ navigation
• スペーシングプリセットを使って適切なパディングを設定

フッターの要件

• ヘッダーのスタイルに合わせる、または引き立てる、幅が制約されたレイアウトグループ
• コンテンツはサイトの種類によって異なります（著作権表示、ソーシャルリンク、連絡先情報など）
• style.css にフッターのマージンリセットを含めます

ブロックパターン

パターンは、再利用可能なブロックコンテンツを登録する PHP ファイルです。

パターンの登録

<?php
/**
 * Title: Hero Section
 * Slug: theme-slug/hero
 * Categories: featured
 */
?>

...

functions.php

functions.php は最小限に保ちます。主な用途は次のとおりです。

Google Fonts の読み込み

重要： フロントエンドとブロックエディターの両方でフォントが読み込まれるよう、必ず wp_enqueue_scripts ではなく enqueue_block_assets フックを使用してください。

<?php
/**
 * Theme functions and definitions
 */

// Enqueue Google Fonts and theme stylesheet for both front-end and block editor
function theme_slug_enqueue_assets() {
    wp_enqueue_style(
        'theme-slug-fonts',
        'https://fonts.googleapis.com/css2?family=Clash+Display:wght@400;500;600;700&family=DM+Sans:wght@400;500;600&display=swap',
        array(),
        null
    );

    wp_enqueue_style(
        'theme-slug-style',
        get_stylesheet_uri(),
        array( 'theme-slug-fonts' ),
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'enqueue_block_assets', 'theme_slug_enqueue_assets' );

// Register block patterns
function theme_slug_register_patterns() {
    register_block_pattern_category(
        'theme-slug',
        array( 'label' => __( 'Theme Patterns', 'theme-slug' ) )
    );
}
add_action( 'init', 'theme_slug_register_patterns' );

生成コードのセキュリティ

• functions.php がユーザー由来の値を出力する場合は、WordPress のエスケープ関数を使用します。
  • HTML コンテキスト：esc_html()
  • 属性コンテキスト：esc_attr()
  • URL コンテキスト：esc_url()
• 生成するテーマコードでは、eval()、create_function()、shell_exec()、exec()、system() を使用しないでください。
• ハードコードされたコンテンツを含む静的ブロックテーマ（デフォルト）では、エスケープは不要です。WordPress のコアブロックが処理します。エスケープが必要なのは、動的データを出力する PHP を生成する場合のみです。

style.css

style.css ファイルにはテーマのメタデータとカスタム CSS を記述します。 ** 重要 ** デザインに含まれるカスタム CSS のうち、theme.json では実現できないものは、必ず style.css に反映してください。特に、アニメーションや動きなど、デザインの美しさに不可欠なレイアウトや構成の手法が対象です。

/*
Theme Name: Theme Name
Theme URI: https://example.com
Author: Author Name
Author URI: https://example.com
Description: A beautiful WordPress block theme
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: theme-slug
*/

ブロックテーマのアニメーションと動き

アニメーションはブロックテーマに動きを与えますが、WordPress のブロックマークアップでは、CSS アニメーションをブロックに適用するための特定のパターンが必要です。

className パターン

ブロックに className JSON 属性を使ってアニメーションクラスを追加します。WordPress はこれをラッパー div のクラスとして出力します。

<div class="wp-block-group alignfull fade-up">
  
</div>

これは、グループ、カラム、見出し、段落、ボタン、画像など、あらゆるブロックで使えます。

<h2 class="wp-block-heading slide-in-left">Features</h2>



<div class="wp-block-columns alignwide stagger-children">
  ...
</div>

style.css のアニメーションクラス

各テーマの style.css に、以下のクラスを生成して適用します（以下はあくまで例であり、これらに限定されません）。

表示時のアニメーション：

.fade-up {
  opacity: 0;
  transform: translateY(30px);
  animation: fadeUp 0.6s ease forwards;
}
.fade-in {
  opacity: 0;
  animation: fadeIn 0.6s ease forwards;
}
.slide-in-left {
  opacity: 0;
  transform: translateX(-40px);
  animation: slideIn 0.7s ease forwards;
}
.slide-in-right {
  opacity: 0;
  transform: translateX(40px);
  animation: slideIn 0.7s ease forwards;
}

@keyframes fadeUp { to { opacity: 1; transform: translateY(0); } }
@keyframes fadeIn { to { opacity: 1; } }
@keyframes slideIn { to { opacity: 1; transform: translateX(0); } }

子要素の順次表示 — nth-child で遅延を適用します：

.stagger-children > * {
  opacity: 0;
  transform: translateY(20px);
  animation: fadeUp 0.5s ease forwards;
}
.stagger-children > *:nth-child(1) { animation-delay: 0.1s; }
.stagger-children > *:nth-child(2) { animation-delay: 0.2s; }
.stagger-children > *:nth-child(3) { animation-delay: 0.3s; }
.stagger-children > *:nth-child(4) { animation-delay: 0.4s; }

インタラクティブなトランジション：

.hover-lift {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.hover-lift:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0,0,0,0.15);
}
.hover-glow {
  transition: box-shadow 0.3s ease;
}
.hover-glow:hover {
  box-shadow: 0 0 20px rgba(var(--wp--preset--color--accent-rgb, 0,0,0), 0.3);
}

継続的な環境アニメーション：

.float {
  animation: float 3s ease-in-out infinite;
}
@keyframes float {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-10px); }
}
.pulse-subtle {
  animation: pulse 2s ease-in-out infinite;
}
@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.7; }
}

functions.php によるスクロール連動の表示

最も効果的なアニメーションパターンである、ユーザーのスクロールに合わせたセクションの表示には、小さな IntersectionObserver スクリプトが必要です。これを functions.php に追加します。

// Enqueue scroll animation observer
function theme_slug_scroll_animations() {
    wp_add_inline_script( 'theme-slug-style', "
        document.addEventListener('DOMContentLoaded', function() {
            var els = document.querySelectorAll('.animate-on-scroll');
            if (!els.length) return;
            var observer = new IntersectionObserver(function(entries) {
                entries.forEach(function(entry) {
                    if (entry.isIntersecting) {
                        entry.target.classList.add('is-visible');
                        observer.unobserve(entry.target);
                    }
                });
            }, { threshold: 0.15 });
            els.forEach(function(el) { observer.observe(el); });
        });
    " );
}
add_action( 'enqueue_block_assets', 'theme_slug_scroll_animations' );

注： wp_add_inline_script には、登録済みのスクリプトハンドルが必要です。ブロックテーマではスクリプトが登録されていない場合もあるため、より確実な方法はスクリプトを直接出力することです。

// Scroll animation observer — outputs inline script
function theme_slug_scroll_animations() {
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function() {
        var els = document.querySelectorAll('.animate-on-scroll');
        if (!els.length) return;
        var observer = new IntersectionObserver(function(entries) {
            entries.forEach(function(entry) {
                if (entry.isIntersecting) {
                    entry.target.classList.add('is-visible');
                    observer.unobserve(entry.target);
                }
            });
        }, { threshold: 0.15 });
        els.forEach(function(el) { observer.observe(el); });
    });
    </script>
    <?php
}
add_action( 'wp_footer', 'theme_slug_scroll_animations' );

次に style.css で、要素を最初は非表示にし、.is-visible が追加されたときにアニメーションさせる CSS を組み合わせます。

.animate-on-scroll {
  opacity: 0;
  transform: translateY(30px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}
.animate-on-scroll.is-visible {
  opacity: 1;
  transform: translateY(0);
}

セクションレベルの Group ブロックには className: "animate-on-scroll" を使用します。

<div class="wp-block-group alignfull animate-on-scroll">
  
</div>

prefers-reduced-motion（必須）

すべてのテーマで、以下を style.css に必ず含めてください。

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

アニメーションの量

すべての要素にアニメーションを付ける必要はありません。以下を優先してください。

• ヒーローセクションの表示 — 最初の印象を決める要素です（フェードアップ、拡大、スライドなど）。
• スクロールに合わせたセクションの表示 — animate-on-scroll を付ける主要なコンテンツブロックです。
• インタラクティブな要素 — hover-lift を付けたカードや、トランジションを付けたボタンです。
• 装飾的な環境アニメーションを1～2個 — 浮遊する図形、グラデーションの変化、または脈動するアクセントなどです。

見出し、段落、ボタンを一つひとつすべてアニメーションさせるのは避けてください。見た目の楽しさではなく、視覚的なノイズにつながります。

横並びのカードレイアウト

高さと幅をそろえたカードを並べる場合（CTA を下揃えにする場合も含む）は、ユーザーから別の指定がない限り、以下の構造を使用してください。

Columns (className: "equal-cards")
  └── Column
        verticalAlignment: "stretch"
        width: "X%" where X = 100 / number_of_cards (e.g., 2 cards = 50%, 3 cards = 33.33%, 4 cards = 25%)
        └── Group [card wrapper]
              └── [content: headings, paragraphs, images*, lists]
              └── (optional) Buttons (className: "cta-bottom")

幅のルール：同じ行のカードはすべて同じ幅にする必要があります。各列の幅は 100% / カードの数 で計算します（例：カードが3枚の場合は各列33.33%）。すべての列幅の合計は必ず正確に100%にしてください。親要素の幅を超えてはいけません。

*カード内の画像：style="height:200px;object-fit:cover;width:100%"

必須 CSS（style.css）：

.equal-cards > .wp-block-column {
  display: flex;
  flex-direction: column;
  flex-grow: 0;
}
.equal-cards > .wp-block-column > .wp-block-group {
  display: flex;
  flex-direction: column;
  flex-grow: 1;
}

存在する場合は、別途指定がない限り、CTA が下揃えになるようにしてください。

.equal-cards .cta-bottom {
  margin-top: auto;
  justify-content: center;
}

フッターの上マージンをリセットするため、以下の CSS を必ず追加してください。

.wp-site-blocks > footer {
  margin-block-start: 0;
}

ランディングページの構成

ホームページのブロックマークアップを生成するときは、テンプレートを組み立てるのではなく、ランディングページのデザイナーとして考えてください。ユーザーがスクロールするにつれてリズムと視覚的なインパクトが生まれるよう、各セクションは全幅で、それぞれがはっきりと異なる帯状のデザインにしてください。

セクションの構成

• セクションのマージンをリセットする：ランディングページのセクションを囲むトップレベルの Group ブロックすべてに、"style":{"spacing":{"margin":{"top":"0"}}} を追加します。これにより、.wp-site-blocks の直接の子要素に対する WordPress のデフォルトの上マージンが上書きされ、ユーザーはエディターで簡単に調整できます。
• セクションのレイアウト幅：ヒーローセクション、ヘッダーグループ、カバーブロック、特徴のグリッドには、デフォルトの狭いコンテンツ幅ではなく、"align":"wide" または "align":"full" を使用します。デフォルト（コンテンツ）配置を使用するのは、テキスト中心の読み物用セクションに限ります。
• <inner-blocks> は使用しないでください。各ブロック内に展開済みのマークアップをすべて出力します。
• カラムの配置：特に指示がない限り、wp:columns ブロックには必ず "align":"wide" を設定し（ラッパーの div に alignwide クラスも追加します）。
• 装飾目的の HTML コメントは禁止：テンプレート、テンプレートパーツ、パターンに、や のようなセクション名を示すコメントを挿入しないでください。WordPress のブロックコメント（``）のみ使用できます。

ホームページの主要セクションはすべて alignfull にする必要があります。つまり、ビューポートの端から端まで表示します。内部のコンテンツ幅は制限できますが、セクションのラッパーは画面幅いっぱいに広げます。これは、全幅のラッパーと制約されたコンテンツを組み合わせるパターンです。

``

ホームページのセクションに "align":"full" を設定せず、{"layout":{"type":"constrained"}} だけを使用することは絶対に避けてください。 alignfull がないと、セクションは contentSize（800px）で表示され、ページが狭く単調になります。

どのセクションがこのサイトに最適かは、あなたが判断してください。固定的なテンプレートに従わないでください。サイトの種類、対象ユーザー、主な目標を考慮します。

• ポートフォリオでは、全幅のプロジェクトギャラリーが必要です
• SaaS では、価値提案が明確な特徴のグリッドが必要です
• レストランでは、食欲をそそる画像やメニューのセクションが必要です
• エージェンシーでは、事例紹介カードやソーシャルプルーフが必要です
• 脱出ゲームでは、雰囲気と没入感が必要です

ビジュアルのリズム

スクロールに合わせて変化をつけるため、ビジュアル表現を交互に切り替えます。

手法	WordPress での実装
背景の切り替え	backgroundColor を background と surface の間で切り替えます（大胆なセクションでは primary／secondary を使用します）
全幅の画像	"align":"full" とブランドパレットの overlayColor を設定したカバーブロック
端から端まで広がるメディアとテキスト	画像とコンテンツの左右を交互に配置する wp:media-text に "align":"full" を設定
目立つ CTA バンド	primary または accent の背景色を設定した全幅グループと、中央揃えのテキスト
スペーサーによる区切り	余白を作るためにセクション間に wp:spacer を配置

各セクションは、隣接するセクションと見た目がはっきり異なる必要があります。背景色とレイアウトパターンが同じセクションが隣り合うと、ページが単調に感じられます。背景を変更する、画像の位置を左右反転する、グリッドから単一カラムに切り替える、カバーブロックで区切るなどして変化をつけてください。

画像の取り扱い

初期サイトの構築では、ユーザーが提供した画像または画像 URL のみを追加してください。ストック画像の URL はブロックエディターで読み込めないことが多く、デザインが崩れる原因になります。 ユーザーが提供した画像は注意深く確認し、適切であればデザインに取り入れてください。ただし、デザインに合わない場合は無理に使用しないでください。

画像を使わずにビジュアルの豊かさを生み出す

ユーザーが提供した画像や画像 URL のみを使用できるため、それらがない場合は、次の方法で雰囲気や視覚的な魅力を表現してください。

• CSS グラデーション：線形、放射状、円錐状のグラデーションで奥行きと色彩を表現します
• カラーブロック：背景色を大胆に使って視覚的な階層を作ります
• デザインとしてのタイポグラフィ：大きく個性的な見出し、創造的なフォントの組み合わせ、さまざまなサイズや太さのテキストを使います
• CSS パターン：CSS グラデーションを使って繰り返しの背景（ストライプ、ドット、グリッド）を作ります
• シャドウと奥行き：box-shadow、text-shadow、drop-shadow で立体感を加えます
• ボーダーとフレーム：ボーダー、アウトライン、装飾的なフレームを創造的に使います
• 余白とレイアウト：ゆとりのある余白や調整された密度で雰囲気を作ります
• CSS 疑似要素：装飾的なビジュアル要素に ::before と ::after を使います
• カラーオーバーレイ：透明度のある div を重ねて雰囲気を演出します