본문으로 건너뛰기

블록 라이브러리 구축하기

블록 라이브러리는 완전한 페이지를 구성하는 독립적인 섹션 블록 모음입니다. 각 블록은 자체 스키마, 템플릿, 스타일을 갖습니다. 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 블록 아래에 본문 스타일, 기본 레이어 기본값, 사용자 지정 유틸리티를 추가합니다.

본문 스타일은 @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 헬퍼라는 두 가지 공통 메커니즘으로 모든 블록에 일관된 간격, 배경 전환, 패딩 제어를 제공합니다.

섹션 필드

모든 블록에서 참조할 수 있는 공통 필드 정의를 만듭니다.

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"
				}
			]
		}
	]
}

이 필드는 모든 블록의 인스펙터에서 “Section” 탭 아래에 표시됩니다. 사용자는 강조 배경을 켜고 끄거나 아래쪽 패딩을 제거할 수 있습니다. 섹션을 간격 없이 쌓을 때 유용합니다.

섹션 헬퍼

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> 컨테이너용입니다.

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가 style.css을 Tailwind v4 구성 소스로 사용하도록 합니다. 이 설정이 없으면 @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 래퍼는 인스펙터에 두 개의 탭을 만듭니다. 블록 필드용 “Content”와 공통 섹션 컨트롤용 “Section”입니다. 모든 블록이 이 구조를 사용합니다.

필드는 group 컨테이너로 구성됩니다. 그룹을 사용하면 인스펙터에서 관련 필드를 시각적으로 구분할 수 있습니다. 첫 번째 그룹에는 텍스트 필드가, 두 번째 그룹에는 링크 필드가 들어갑니다.

기본값은 블록을 삽입하는 즉시 완성된 모습으로 보이도록 의미 있는 콘텐츠를 제공합니다. 사용자 조작 없이 블록을 추가하는 페이지 구성에서 특히 중요합니다.

이제 템플릿을 작성합니다.

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. <section> 바깥 요소에 useBlockProps 및 섹션 클래스를 적용합니다.
  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 필드 값을 사용하고, 값이 없으면 “Feature”를 표시합니다. 항목이 많을 때도 인스펙터를 사용하기 쉽게 해 줍니다.

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"로 설정하면 사용자는 블록을 추가, 삭제, 재정렬할 수 없습니다. 페이지 구조가 템플릿에 고정됩니다. 다른 잠금 모드와 편집 컨트롤은 페이지 문서를 참조하세요.

확장

최소 라이브러리는 블록 35개로 시작하고, 포괄적인 라이브러리는 814개를 포함합니다. 다음은 일반적인 블록 유형을 사용 빈도가 높은 순서대로 대략 나열한 것입니다.

블록 설명 주요 필드
히어로 주요 CTA가 있는 큰 제목 제목, 설명, 링크
기능 장점 그리드 제목, 제목 및 설명이 있는 반복 입력 항목
CTA 행동 유도 배너 제목, 설명, 링크
가격 요금제 비교 제목, 이름·가격·기능이 있는 반복 입력 항목
사용 후기 고객 인용문 인용문·이름·직책이 있는 반복 입력 항목
FAQ 질문 아코디언 제목, 질문과 답변이 있는 반복 입력 항목
로고 고객 로고 모음 제목(로고는 보통 하드코딩된 SVG)
콘텐츠 텍스트와 이미지가 번갈아 나오는 행 제목·설명·이미지가 있는 반복 입력 항목
쇼케이스 캡션이 있는 전체 너비 이미지 제목, 설명, 이미지
팀 팀원 그리드 이름·직책·이미지가 있는 반복 입력 항목
통계 주요 지표 숫자와 레이블이 있는 반복 입력 항목

각 블록은 같은 패턴을 따릅니다. 탭(Content + Section), 구성용 그룹, 목록용 반복 입력 항목, 일관된 간격을 위한 섹션 헬퍼를 사용합니다. 블록을 두세 개 만들고 나면 나머지는 기계적으로 추가할 수 있습니다.

페이지 추가

라이브러리가 커지면 같은 블록으로 다양한 페이지를 구성할 수 있습니다.

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>

같은 블록을 기본값만 다르게 설정해 여러 페이지에 사용할 수 있습니다. 이것이 라이브러리 방식의 장점입니다. 블록을 한 번 만든 뒤 필요한 만큼 여러 페이지에 구성할 수 있습니다.

다음 단계