Pular para o conteúdo

Criando uma biblioteca de blocos

Uma biblioteca de blocos é um conjunto de blocos de seção independentes que se combinam para formar páginas completas. Cada bloco tem seu próprio esquema, template e estilo. Blockstudio fornece a estrutura: processamento de Tailwind CSS, registro de atributos e sincronização de páginas. Você fornece os blocos.

Este guia mostra como criar uma biblioteca do zero, seguindo a mesma arquitetura usada em centenas de temas de produção. Ao final, você terá um tema funcional com uma seção hero, uma grade de recursos e uma página inicial composta.

Estrutura de pastas

Todos os temas de Blockstudio seguem a mesma estrutura:

Código
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

Os blocos ficam em blockstudio/sections/. Cada bloco é uma pasta com um esquema block.json e um template index.php. As páginas ficam em pages/ e combinam blocos usando a sintaxe <block>.

Arquivos fundamentais

blockstudio.json

Este arquivo configura como Blockstudio processa seu tema. A configuração é igual para todos os temas:

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 remove os estilos padrão dos blocos WordPress. fullWidth faz com que os tipos de post page ocupem a largura total. canvas ativa o modo de canvas do editor para uma experiência de edição mais limpa.

O campo tailwind.config fica intencionalmente vazio. Com Tailwind v4, toda a configuração fica em style.css, seguindo uma abordagem que prioriza CSS.

index.php

O template principal WordPress. É WordPress padrão, sem nada específico de 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>

Adicione um header.php e um footer.php quando precisar de navegação. Por enquanto, um template mínimo basta para renderizar os blocos.

Tokens de design

Toda a tematização acontece em style.css usando a diretiva @theme de Tailwind v4. Esse é o coração do seu sistema de design.

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;
}

Todo tema precisa, no mínimo, de:

Token Finalidade
--font-sans ou --font-serif Tipo de letra principal
--color-bg Fundo da página
--color-elevated Fundo do cartão/superfície
--color-subtle Bordas, divisórias
--color-muted Texto secundário
--color-accent Cor principal da marca

Esses tokens geram utilitários Tailwind automaticamente. --color-accent se torna bg-accent, text-accent, border-accent e assim por diante.

Para um tema claro, inverta os valores:

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;
}

Estilos base e utilitários

Abaixo do bloco @theme, adicione estilos para o body, padrões da camada base e utilitários personalizados.

Os estilos do body devem ficar fora de @layer para que o editor WordPress os aplique:

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

Camada base para os padrões dos elementos:

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

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

	p {
		text-wrap: pretty;
	}
}

Utilitários personalizados para padrões reutilizáveis. Todo tema define um utilitário container para espaçamento consistente entre seções e, normalmente, card, badge e utilitários para botões:

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);
	}
}

Os pseudosseletorres ficam dentro do bloco @utility, usando o aninhamento CSS (&:hover). Nunca os coloque no nome do utilitário. @utility btn-primary:hover {} é inválido e será rejeitado por Tailwind.

@source em linha

Blockstudio examina automaticamente os templates dos blocos em busca de classes Tailwind. Mas classes usadas fora dos templates dos blocos (em functions.php, header.php, index.php) não são examinadas. Declare-as com @source inline:

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

Isso instrui Tailwind a incluir essas classes na saída, embora elas só apareçam em arquivos PHP que não são examinados.

O padrão de seção

O padrão de seção é a convenção mais importante em uma biblioteca de blocos Blockstudio. Ele oferece a todos os blocos espaçamento consistente, alternância de fundo e controle de preenchimento por meio de dois mecanismos compartilhados: um campo personalizado e um helper PHP.

O campo de seção

Crie uma definição de campo compartilhada que todos os blocos possam referenciar:

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

Esse campo aparece no inspetor de cada bloco, em uma aba “Seção”. Os clientes têm dois controles: ativar um fundo de destaque e remover o preenchimento inferior (útil para empilhar seções sem espaços).

O helper de seção

Em functions.php, crie um helper que converta esses atributos em classes 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 );
}

O template de cada bloco chama esse helper na primeira linha. O helper retorna duas strings de classe: uma para o elemento <section> externo e outra para o contêiner <div> interno.

Filtro de configuração Tailwind

Também em functions.php, adicione o filtro que envia seu style.css ao processador Tailwind de Blockstudio:

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 '';
	}
);

Isso instrui Blockstudio a usar seu style.css como fonte de configuração Tailwind v4. Sem isso, seus tokens @theme e definições @utility não estariam disponíveis nos templates dos blocos.

Seu primeiro bloco: Hero

Uma seção hero demonstra o padrão completo de bloco. Comece pelo esquema:

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

Padrões importantes a observar:

O wrapper tabs cria um inspetor com duas abas: “Conteúdo” para os campos do bloco e “Seção” para os controles compartilhados da seção. Todos os blocos usam essa estrutura.

Os campos são organizados em contêineres group. Os grupos separam visualmente campos relacionados no inspetor. O primeiro grupo contém campos de texto; o segundo, campos de link.

Os valores padrão fornecem conteúdo relevante para que o bloco pareça completo assim que for inserido. Isso é fundamental para compor páginas, quando os blocos são adicionados sem interação do usuário.

Agora, o template:

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>

O template segue um padrão consistente:

  1. Chame o helper de seção para obter classes CSS
  2. <section> externo com useBlockProps e classes de seção
  3. <div> interno com classes de contêiner
  4. Conteúdo renderizado a partir de $a (a forma abreviada dos atributos)
  5. Renderização condicional para campos opcionais
  6. Escape adequado: esc_html() para texto, esc_url() para URLs, esc_attr() para atributos

Adicionando repetidores: grade de recursos

Os repetidores permitem que os clientes adicionem, removam e reordenem itens. Uma grade de recursos é o exemplo clássico:

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

A propriedade textMinimized controla qual texto aparece quando uma linha do repetidor está recolhida. Ela lê o valor do campo title e, se estiver vazio, usa “Recurso”. Isso torna o inspetor fácil de usar quando há muitos itens.

A matriz default fornece os itens iniciais. Eles aparecem quando o bloco é inserido pela primeira vez. Sempre forneça valores padrão realistas para que o bloco pareça completo imediatamente.

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>

Os itens do repetidor são acessados como uma matriz simples PHP. Faça um loop com foreach e acesse os campos de cada item por seus id.

Imagens e espaços reservados

Para blocos com imagens, use o tipo de campo files e o componente MediaPlaceholder. O espaço reservado exibe uma área para arrastar e soltar no editor:

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

No template, renderize a imagem com wp_get_attachment_image() e mostre um SVG de espaço reservado quando nenhuma imagem estiver selecionada:

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() retorna um SVG em linha que usa currentColor com a variável --color-accent, adaptando-se automaticamente ao seu tema. Para temas claros, use blockstudio_placeholder_light(). Ambos aceitam um argumento de variante:

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

Compondo páginas

As páginas combinam blocos em layouts completos usando a sintaxe <block>. Crie uma página inicial:

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>

Pronto. Cada elemento <block> insere o bloco com seus valores de atributo padrão. Execute wp bs pages sync para aplicar o código-fonte da página a WordPress.

Para substituir os valores padrão em uma página específica, passe os atributos diretamente:

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

Com templateLock definido como "all", os clientes não podem adicionar, remover ou reorganizar blocos. A estrutura da página fica bloqueada pelo seu template. Consulte Páginas para ver outros modos de bloqueio e controles de edição.

Ampliando a biblioteca

Uma biblioteca mínima começa com 3-5 blocos. Uma biblioteca abrangente tem 8-14. Estes são os tipos de bloco mais comuns, aproximadamente em ordem de frequência:

Bloco Descrição Campos principais
Hero Título grande com chamadas para ação título, descrição, links
Recursos Grade de benefícios título, repetidor com título + descrição
CTA Faixa de chamada para ação título, descrição, link
Preços Comparação de planos título, repetidor com nome + preço + recursos
Depoimentos Citações de clientes repetidor com citação + nome + função
FAQ Acordeão de perguntas título, repetidor com pergunta + resposta
Logotipos Grade de logotipos de clientes título (os logotipos costumam ser SVGs codificados diretamente)
Conteúdo Linhas alternadas de texto + imagem repetidor com título + descrição + imagem
Destaque Imagem em largura total com legenda título, descrição, imagem
Equipe Grade de integrantes da equipe título, repetidor com nome + função + imagem
Estatísticas Métricas principais repetidor com número + rótulo

Todos os blocos seguem o mesmo padrão: abas (Conteúdo + Seção), grupos para organização, repetidores para listas e o helper de seção para espaçamento consistente. Depois de criar dois ou três blocos, adicionar mais se torna mecânico.

Adicionando mais páginas

À medida que sua biblioteca cresce, componha páginas diferentes com os mesmos blocos:

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>

Os mesmos blocos atendem a várias páginas, cada uma com valores padrão diferentes. Essa é a vantagem da abordagem de biblioteca: crie os blocos uma vez e combine-os em quantas páginas precisar.

Próximas etapas