コンテンツへスキップ

ブロックライブラリの構築

ブロックライブラリとは、組み合わせてページ全体を構成する、自己完結したセクションブロックの集合です。各ブロックは独自のスキーマ、テンプレート、スタイルを持ちます。Blockstudioはフレームワークを提供し、Tailwind CSSの処理、属性登録、ページ同期を担います。ブロックはあなたが用意します。

このガイドでは、数百の本番テーマで使われているアーキテクチャに沿って、ライブラリをゼロから構築します。最後には、ヒーロー、特徴グリッド、構成済みのホームページを備えた動作するテーマが完成します。

フォルダー構成

すべてのBlockstudioテーマは、同じレイアウトに従います:

コード
my-theme/
├── style.css                           # WordPress header + Tailwind v4 config
├── blockstudio.json                    # Blockstudio settings
├── functions.php                       # Section helper + Tailwind filter
├── index.php                           # Main WordPress template
├── blockstudio/
│   ├── fields/
│   │   └── section/
│   │       └── field.json              # Shared section controls
│   └── sections/
│       ├── hero/
│       │   ├── block.json
│       │   └── index.php
│       └── features/
│           ├── block.json
│           └── index.php
└── pages/
    └── home/
        ├── page.json
        └── index.php

ブロックはblockstudio/sections/に配置します。各ブロックは、block.jsonスキーマとindex.phpテンプレートを含むフォルダーです。ページはpages/に配置し、<block>構文を使ってブロックを組み合わせます。

基本ファイル

blockstudio.json

このファイルでは、Blockstudioによるテーマの処理方法を設定します。設定内容はすべてのテーマで共通です:

JSON
{
	"assets": {
		"enqueue": true,
		"reset": {
			"enabled": true,
			"fullWidth": ["page"]
		},
		"minify": { "css": true, "js": true },
		"process": { "scss": false, "scssFiles": true }
	},
	"tailwind": {
		"enabled": true,
		"config": ""
	},
	"dev": {
		"canvas": { "enabled": true }
	},
	"$schema": "https://blockstudio.dev/schema/blockstudio"
}

resetはデフォルトのWordPressブロックスタイルを削除します。fullWidthはpage投稿タイプを全幅に広げます。canvasを有効にすると、よりすっきり編集できるエディターキャンバスモードになります。

tailwind.configフィールドは意図的に空にしています。Tailwind v4では、style.cssを使うCSSファーストのアプローチで設定をすべて管理します。

index.php

メインのWordPressテンプレートです。標準のWordPressで、Blockstudio固有のものはありません:

PHP
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
	<meta charset="<?php bloginfo( 'charset' ); ?>">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

<main>
<?php
if ( have_posts() ) {
	while ( have_posts() ) {
		the_post();
		the_content();
	}
}
?>
</main>

<?php wp_footer(); ?>
</body>
</html>

ナビゲーションが必要になったら、header.phpとfooter.phpを追加します。今はブロックを描画できる最小限のテンプレートで十分です。

デザイントークン

テーマ設定はすべてstyle.cssで行い、Tailwind v4の@themeディレクティブを使います。ここがデザインシステムの要です。

CSS
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/

@theme {
	--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
	--color-bg: #050505;
	--color-elevated: #111111;
	--color-subtle: rgb(255 255 255 / 0.06);
	--color-muted: #888888;
	--color-accent: #6366f1;
	--color-accent-hover: #4f46e5;
}

すべてのテーマに、最低限次の項目が必要です:

トークン 用途
--font-sansまたは--font-serif 基本の書体
--color-bg ページの背景
--color-elevated カードやサーフェスの背景
--color-subtle 枠線、区切り線
--color-muted 補助テキスト
--color-accent ブランドの基本色

これらのトークンからTailwindのユーティリティが自動生成されます。--color-accentはbg-accent、text-accent、border-accentなどになります。

ライトテーマでは、値を反転させます:

CSS
@theme {
	--font-serif: 'Zilla Slab', serif;
	--font-sans: 'DM Sans', sans-serif;
	--color-bg: #f5f0e8;
	--color-elevated: #ece6da;
	--color-heading: #2c1810;
	--color-body: #6b5c4f;
	--color-muted: #9a8b7d;
	--color-accent: #2d5016;
	--color-subtle: #d9d1c4;
}

基本スタイルとユーティリティ

@themeブロックの下に、bodyスタイル、基本レイヤーのデフォルト、カスタムユーティリティを追加します。

bodyスタイルは@layerの外に記述してください。WordPressエディターに反映させるためです:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

基本レイヤーで要素のデフォルトを定義します:

CSS
@layer base {
	section {
		@apply relative overflow-hidden;
	}

	h1, h2, h3 {
		text-wrap: balance;
	}

	p {
		text-wrap: pretty;
	}
}

再利用できるパターンにはカスタムユーティリティを使います。どのテーマでも一貫したセクション間隔を保つcontainerユーティリティを定義し、通常はcard、badge、ボタン用のユーティリティも定義します:

CSS
@utility container-px {
	@apply mx-auto max-w-5xl px-6;
}

@utility container {
	@apply container-px py-24 sm:py-32;
}

@utility container-no-pb {
	@apply pb-0 sm:pb-0;
}

@utility card {
	@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;

	&:hover {
		border-color: rgb(255 255 255 / 0.1);
	}
}

@utility badge {
	@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}

@utility btn-primary {
	@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;

	&:hover {
		@apply bg-accent-hover;
	}
}

@utility btn-secondary {
	@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;

	&:hover {
		border-color: rgb(255 255 255 / 0.15);
		background: rgb(255 255 255 / 0.04);
	}
}

疑似セレクターは@utilityブロック内で、CSSのネスト構文(&:hover)を使って記述します。ユーティリティ名には含めないでください。@utility btn-primary:hover {}は無効なため、Tailwindに拒否されます。

@sourceをインラインで指定

Blockstudioはブロックテンプレート内のTailwindクラスを自動的にスキャンします。ただし、ブロックテンプレート以外(functions.php、header.php、index.php)で使われるクラスはスキャンされません。@source inlineを使って宣言してください:

CSS
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");

これにより、スキャン対象外のPHPファイルにしか記述されていなくても、これらのクラスが出力に含まれるようTailwindに指示します。

セクションのパターン

セクションのパターンは、Blockstudioブロックライブラリで最も重要な規約です。カスタムフィールドとPHPヘルパーという2つの共通の仕組みにより、すべてのブロックで間隔、背景の切り替え、余白を一貫して制御できます。

セクションフィールド

すべてのブロックから参照できる共通のフィールド定義を作成します:

JSON
{
	"$schema": "https://blockstudio.dev/schema/field",
	"name": "section",
	"title": "Section",
	"attributes": [
		{
			"type": "group",
			"attributes": [
				{
					"id": "removeBottomPadding",
					"type": "toggle",
					"label": "Remove bottom padding"
				},
				{
					"id": "accentBg",
					"type": "toggle",
					"label": "Accent background"
				}
			]
		}
	]
}

このフィールドは、各ブロックのインスペクターにある「セクション」タブに表示されます。クライアントは2つの項目を操作できます。アクセント背景の切り替えと、下部の余白の削除です(セクション間の隙間をなくして連結する場合に便利です)。

セクションヘルパー

functions.phpに、これらの属性をCSSクラスに変換するヘルパーを作成します:

PHP
<?php
/**
 * My Theme functions.
 *
 * @package My_Theme
 */

/**
 * Returns section and container class strings based on block attributes.
 *
 * @param array  $a               Block attributes.
 * @param string $extra_section   Additional classes for the section element.
 * @param string $extra_container Additional classes for the container element.
 * @return array Array of [ section_classes, container_classes ].
 */
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
	$section   = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
	$container = 'container';

	if ( ! empty( $a['removeBottomPadding'] ) ) {
		$container .= ' container-no-pb';
	}

	if ( $extra_section ) {
		$section .= ' ' . $extra_section;
	}

	if ( $extra_container ) {
		$container .= ' ' . $extra_container;
	}

	return array( $section, $container );
}

各ブロックのテンプレートでは、このヘルパーを先頭の行で呼び出します。ヘルパーは、外側の<section>要素用と内側の<div>コンテナ用の、2つのクラス文字列を返します。

Tailwind設定フィルター

さらにfunctions.phpに、style.cssをBlockstudioのTailwindプロセッサーに渡すフィルターを追加します:

PHP
add_filter(
	'blockstudio/settings/tailwind/config',
	function () {
		$style = get_stylesheet_directory() . '/style.css';

		if ( file_exists( $style ) ) {
			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
			return file_get_contents( $style );
		}

		return '';
	}
);

これによりBlockstudioは、Tailwind v4の設定ソースとしてstyle.cssを使います。これがないと、@themeトークンと@utilityの定義をブロックテンプレートで利用できません。

最初のブロック: ヒーロー

ヒーローセクションは、ブロックのパターン全体を示す例です。まずスキーマを作成します:

JSON
{
	"$schema": "https://blockstudio.dev/schema/block",
	"name": "my-theme/hero",
	"title": "Hero",
	"category": "my-theme",
	"icon": "star-filled",
	"description": "Full-width hero section with heading, description, and buttons.",
	"blockstudio": {
		"attributes": [
			{
				"type": "tabs",
				"tabs": [
					{
						"title": "Content",
						"attributes": [
							{
								"type": "group",
								"attributes": [
									{
										"id": "heading",
										"type": "text",
										"label": "Heading",
										"default": "Build beautiful websites without the complexity"
									},
									{
										"id": "description",
										"type": "textarea",
										"label": "Description",
										"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
									}
								]
							},
							{
								"type": "group",
								"attributes": [
									{
										"id": "primaryButton",
										"type": "link",
										"label": "Primary Button",
										"default": {
											"title": "Get Started",
											"url": "#"
										}
									},
									{
										"id": "secondaryButton",
										"type": "link",
										"label": "Secondary Button",
										"default": {
											"title": "Learn More",
											"url": "#"
										}
									}
								]
							}
						]
					},
					{
						"title": "Section",
						"attributes": [
							{ "type": "custom/section" }
						]
					}
				]
			}
		]
	}
}

注目すべきポイント:

tabsラッパーを使うと、2つのタブを持つインスペクターができます。ブロックのフィールドを表示する「コンテンツ」と、共通のセクション設定を表示する「セクション」です。どのブロックもこの構造を使います。

フィールドはgroupコンテナにまとめます。グループを使うと、関連するフィールドをインスペクター上で視覚的に分けられます。最初のグループにはテキストフィールド、2つ目のグループにはリンクフィールドを配置します。

デフォルト値に意味のあるコンテンツを設定すると、ブロックを挿入した時点で完成した見た目になります。ユーザーが何も操作せずにブロックを追加するページ構成では、特に重要です。

次にテンプレートを作成します:

PHP
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>

<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
	<div class="<?php echo esc_attr( $container_classes ); ?>">
		<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
			<?php echo esc_html( $a['heading'] ); ?>
		</h1>

		<?php if ( ! empty( $a['description'] ) ) : ?>
			<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
				<?php echo esc_html( $a['description'] ); ?>
			</p>
		<?php endif; ?>

		<div class="mt-10 flex items-center justify-center gap-x-4">
			<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
				<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
					<?php echo esc_html( $a['primaryButton']['title'] ); ?>
				</a>
			<?php endif; ?>

			<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
				<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
					<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
				</a>
			<?php endif; ?>
		</div>
	</div>
</section>

テンプレートは次の一貫したパターンに従います:

  1. セクションヘルパーを呼び出し、CSSクラスを取得
  2. useBlockPropsとセクションクラスを指定した外側の<section>
  3. コンテナクラスを指定した内側の<div>
  4. $a(属性の簡略記法)からコンテンツを出力
  5. オプションフィールドを条件付きで描画
  6. 適切にエスケープ: テキストにはesc_html()、URLにはesc_url()、属性にはesc_attr()

リピーターの追加: 特徴グリッド

リピーターを使うと、クライアントは項目の追加、削除、並べ替えができます。特徴グリッドは代表的な例です:

JSON
{
	"$schema": "https://blockstudio.dev/schema/block",
	"name": "my-theme/features",
	"title": "Features",
	"category": "my-theme",
	"icon": "grid-view",
	"description": "Feature grid with titles and descriptions.",
	"blockstudio": {
		"attributes": [
			{
				"type": "tabs",
				"tabs": [
					{
						"title": "Content",
						"attributes": [
							{
								"type": "group",
								"attributes": [
									{
										"id": "heading",
										"type": "text",
										"label": "Heading",
										"default": "Everything you need"
									},
									{
										"id": "description",
										"type": "textarea",
										"label": "Description",
										"default": "Our toolkit gives you the building blocks to go from idea to production."
									}
								]
							},
							{
								"type": "group",
								"attributes": [
									{
										"id": "features",
										"type": "repeater",
										"label": "Features",
										"textMinimized": {
											"id": "title",
											"fallback": "Feature"
										},
										"default": [
											{
												"title": "Lightning Fast",
												"description": "Optimized for performance with minimal overhead."
											},
											{
												"title": "Fully Responsive",
												"description": "Every component adapts across all screen sizes."
											},
											{
												"title": "Easy to Customize",
												"description": "Adjust every detail to match your brand."
											}
										],
										"attributes": [
											{
												"id": "title",
												"type": "text",
												"label": "Title"
											},
											{
												"id": "description",
												"type": "textarea",
												"label": "Description"
											}
										]
									}
								]
							}
						]
					},
					{
						"title": "Section",
						"attributes": [
							{ "type": "custom/section" }
						]
					}
				]
			}
		]
	}
}

textMinimizedプロパティは、リピーターの行を折りたたんだときに表示するテキストを指定します。titleフィールドの値を読み取り、空の場合は「特徴」を表示します。項目が多くてもインスペクターを使いやすくできます。

default配列で初期項目を指定します。これらはブロックを最初に挿入したときに表示されます。ブロックがすぐに完成した見た目になるよう、常に現実的な初期値を用意してください。

PHP
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>

<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
	<div class="<?php echo esc_attr( $container_classes ); ?>">
		<?php if ( ! empty( $a['heading'] ) ) : ?>
			<div class="text-center max-w-2xl mx-auto">
				<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
					<?php echo esc_html( $a['heading'] ); ?>
				</h2>

				<?php if ( ! empty( $a['description'] ) ) : ?>
					<p class="mt-4 text-base leading-relaxed text-muted">
						<?php echo esc_html( $a['description'] ); ?>
					</p>
				<?php endif; ?>
			</div>
		<?php endif; ?>

		<?php if ( ! empty( $a['features'] ) ) : ?>
			<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
				<?php foreach ( $a['features'] as $feature ) : ?>
					<div class="card">
						<h3 class="text-sm font-medium">
							<?php echo esc_html( $feature['title'] ); ?>
						</h3>
						<p class="mt-2 text-sm leading-relaxed text-muted">
							<?php echo esc_html( $feature['description'] ); ?>
						</p>
					</div>
				<?php endforeach; ?>
			</div>
		<?php endif; ?>
	</div>
</section>

リピーターの項目は、通常のPHP配列として扱います。foreachでループし、各項目のフィールドにはそれぞれのidからアクセスします。

画像とプレースホルダー

画像を含むブロックでは、filesフィールドタイプとMediaPlaceholderコンポーネントを使います。プレースホルダーはエディターにドラッグ&ドロップ領域を表示します:

JSON
{
	"id": "image",
	"type": "files",
	"label": "Image"
}

テンプレートではwp_get_attachment_image()を使って画像を描画し、画像が選択されていない場合はプレースホルダーのSVGを表示します:

PHP
<div class="overflow-hidden rounded-2xl bg-elevated">
	<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
	<?php if ( ! empty( $a['image'] ) ) : ?>
		<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
	<?php else : ?>
		<?php echo blockstudio_placeholder_dark(); ?>
	<?php endif; ?>
</div>

blockstudio_placeholder_dark()は、--color-accent変数を使ってcurrentColorを適用するインラインSVGを返すため、テーマに合わせて自動的に調整されます。ライトテーマではblockstudio_placeholder_light()を使います。どちらもバリアント引数を受け取ります:

PHP
blockstudio_placeholder_dark( 'dashboard' )  // Dashboard mockup
blockstudio_placeholder_dark( 'chart' )      // Chart illustration
blockstudio_placeholder_dark( 'product' )    // Product shot

ページの構成

ページでは<block>構文を使ってブロックを組み合わせ、レイアウト全体を構成します。ホームページを作成します:

JSON
{
	"name": "home",
	"title": "Home",
	"slug": "home",
	"postType": "page",
	"postStatus": "publish",
	"templateLock": "all"
}
PHP
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>

これで完了です。各<block>要素でブロックを挿入すると、属性にはデフォルト値が使われます。wp bs pages syncを実行し、ページのソースをWordPressに適用します。

特定のページでデフォルト値を上書きするには、属性を直接渡します:

PHP
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>

templateLockを"all"に設定すると、クライアントはブロックを追加、削除、並べ替えできません。ページ構造はテンプレートに固定されます。ほかのロックモードや編集コントロールについては、Pagesを参照してください。

規模の拡大

最小限のライブラリは3~5個のブロックから始められます。充実したライブラリには8~14個が含まれます。よく使われるブロックを、おおよその使用頻度順に示します:

ブロック 説明 主なフィールド
ヒーロー 大きな見出しとCTA 見出し、説明、リンク
特徴 メリットのグリッド 見出し、タイトルと説明を含むリピーター
CTA 行動喚起バナー 見出し、説明、リンク
価格 プランの比較 見出し、名前・価格・特徴を含むリピーター
お客様の声 顧客のコメント コメント・名前・役職を含むリピーター
FAQ 質問のアコーディオン 見出し、質問と回答を含むリピーター
ロゴ クライアントロゴの一覧 見出し(ロゴは通常SVGで直接記述)
コンテンツ テキストと画像を交互に配置した行 見出し・説明・画像を含むリピーター
ショーケース 全幅画像とキャプション 見出し、説明、画像
チーム チームメンバーのグリッド 名前・役職・画像を含むリピーター
統計 主要指標 数値とラベルを含むリピーター

各ブロックは同じパターンに従います。タブ(コンテンツとセクション)、整理用のグループ、リスト用のリピーター、間隔を一貫させるセクションヘルパーです。ブロックを2つか3つ作れば、あとは同じ手順で追加できます。

ページを追加する

ライブラリが大きくなったら、同じブロックを組み合わせて別のページを作成できます:

PHP
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
PHP
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>

同じブロックを複数のページで使い、それぞれ異なるデフォルト値を設定できます。これがライブラリアプローチの強みです。ブロックを一度作れば、必要な数だけページを構成できます。

次のステップ