ブロックライブラリの構築
ブロックライブラリとは、組み合わせてページ全体を構成する、自己完結したセクションブロックの集合です。各ブロックは独自のスキーマ、テンプレート、スタイルを持ちます。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によるテーマの処理方法を設定します。設定内容はすべてのテーマで共通です:
{
"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固有のものはありません:
<!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ディレクティブを使います。ここがデザインシステムの要です。
/*
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などになります。
ライトテーマでは、値を反転させます:
@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エディターに反映させるためです:
body {
@apply bg-bg font-sans text-white antialiased;
}
基本レイヤーで要素のデフォルトを定義します:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
再利用できるパターンにはカスタムユーティリティを使います。どのテーマでも一貫したセクション間隔を保つcontainerユーティリティを定義し、通常はcard、badge、ボタン用のユーティリティも定義します:
@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を使って宣言してください:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
これにより、スキャン対象外のPHPファイルにしか記述されていなくても、これらのクラスが出力に含まれるようTailwindに指示します。
セクションのパターン
セクションのパターンは、Blockstudioブロックライブラリで最も重要な規約です。カスタムフィールドとPHPヘルパーという2つの共通の仕組みにより、すべてのブロックで間隔、背景の切り替え、余白を一貫して制御できます。
セクションフィールド
すべてのブロックから参照できる共通のフィールド定義を作成します:
{
"$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
/**
* 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プロセッサーに渡すフィルターを追加します:
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の定義をブロックテンプレートで利用できません。
最初のブロック: ヒーロー
ヒーローセクションは、ブロックのパターン全体を示す例です。まずスキーマを作成します:
{
"$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 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>
テンプレートは次の一貫したパターンに従います:
- セクションヘルパーを呼び出し、CSSクラスを取得
useBlockPropsとセクションクラスを指定した外側の<section>- コンテナクラスを指定した内側の
<div> $a(属性の簡略記法)からコンテンツを出力- オプションフィールドを条件付きで描画
- 適切にエスケープ: テキストには
esc_html()、URLにはesc_url()、属性にはesc_attr()
リピーターの追加: 特徴グリッド
リピーターを使うと、クライアントは項目の追加、削除、並べ替えができます。特徴グリッドは代表的な例です:
{
"$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 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コンポーネントを使います。プレースホルダーはエディターにドラッグ&ドロップ領域を表示します:
{
"id": "image",
"type": "files",
"label": "Image"
}
テンプレートではwp_get_attachment_image()を使って画像を描画し、画像が選択されていない場合はプレースホルダーのSVGを表示します:
<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()を使います。どちらもバリアント引数を受け取ります:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
ページの構成
ページでは<block>構文を使ってブロックを組み合わせ、レイアウト全体を構成します。ホームページを作成します:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
これで完了です。各<block>要素でブロックを挿入すると、属性にはデフォルト値が使われます。wp bs pages syncを実行し、ページのソースをWordPressに適用します。
特定のページでデフォルト値を上書きするには、属性を直接渡します:
<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つ作れば、あとは同じ手順で追加できます。
ページを追加する
ライブラリが大きくなったら、同じブロックを組み合わせて別のページを作成できます:
<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>
<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>
同じブロックを複数のページで使い、それぞれ異なるデフォルト値を設定できます。これがライブラリアプローチの強みです。ブロックを一度作れば、必要な数だけページを構成できます。
次のステップ
- 属性の登録:フィールドタイプとプロパティの完全なリファレンス
- フィールドタイプ:利用可能なフィールドタイプ一覧
- フィールドパターンのレシピ集:条件付きグループ、スマートセレクト、リピーターの実例
- Pages:テンプレートのロック、編集モード、キーを使ったマージ
- ファイルベースのページ構築:ページテンプレートと同期の実践ガイド
- インタラクティビティ:ブロックへのクライアント側の動作の追加