Saltar al contenido

Crear una biblioteca de bloques

Una biblioteca de bloques es un conjunto de bloques de sección independientes que se combinan para crear páginas completas. Cada bloque tiene su propio esquema, plantilla y estilos. Blockstudio proporciona el marco: procesamiento de Tailwind CSS, registro de atributos y sincronización de páginas. Usted aporta los bloques.

Esta guía explica cómo crear una biblioteca desde cero, siguiendo la misma arquitectura que se usa en cientos de temas de producción. Al terminar, tendrá un tema funcional con una sección principal, una cuadrícula de características y una página de inicio compuesta.

Estructura de carpetas

Todos los temas de Blockstudio siguen la misma estructura:

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

Los bloques están en blockstudio/sections/. Cada bloque es una carpeta con un esquema block.json y una plantilla index.php. Las páginas están en pages/ y combinan bloques mediante la sintaxis <block>.

Archivos básicos

blockstudio.json

Este archivo configura cómo Blockstudio procesa el tema. La configuración es la misma para todos los 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 elimina los estilos predeterminados de los bloques de WordPress. fullWidth hace que los tipos de contenido page ocupen todo el ancho. canvas activa el modo de lienzo del editor para facilitar la edición.

El campo tailwind.config está vacío intencionalmente. Con Tailwind v4, toda la configuración reside en style.css mediante el enfoque centrado en CSS.

index.php

La plantilla principal de WordPress. Es WordPress estándar, sin 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>

Añada un header.php y un footer.php cuando necesite navegación. Por ahora, basta con una plantilla mínima para renderizar bloques.

Tokens de diseño

Todo el diseño del tema se define en style.css mediante la directiva @theme de Tailwind v4. Este es el núcleo de su sistema de diseño.

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 necesita como mínimo:

Token Propósito
--font-sans o --font-serif Tipografía principal
--color-bg Fondo de página
--color-elevated Fondo de tarjetas/superficies
--color-subtle Bordes y separadores
--color-muted Texto secundario
--color-accent Color principal de marca

Estos tokens generan utilidades de Tailwind automáticamente. --color-accent se convierte en bg-accent, text-accent, border-accent, etc.

Para un tema claro, invierta los 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 y utilidades

Debajo del bloque @theme, añada estilos para el cuerpo, valores predeterminados de la capa base y utilidades personalizadas.

Los estilos del cuerpo deben estar fuera de @layer para que el editor de WordPress los aplique:

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

Capa base para los valores predeterminados de los elementos:

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

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

	p {
		text-wrap: pretty;
	}
}

Utilidades personalizadas para patrones reutilizables. Todos los temas definen una utilidad container para mantener un espaciado uniforme entre secciones y, normalmente, también card, badge y utilidades para botones:

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

Los seudoselectores van dentro del bloque @utility, usando el anidamiento CSS (&:hover). Nunca los incluya en el nombre de la utilidad. @utility btn-primary:hover {} no es válido y Tailwind lo rechazará.

@source en línea

Blockstudio analiza automáticamente las clases de Tailwind en las plantillas de sus bloques. Pero no analiza las clases que se usan fuera de ellas (en functions.php, header.php, index.php). Declárelas con @source inline:

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

Esto indica a Tailwind que incluya estas clases en la salida, aunque solo aparezcan en archivos PHP que no se analizan.

El patrón de sección

El patrón de sección es la convención más importante de una biblioteca de bloques Blockstudio. Permite controlar de forma uniforme el espaciado, el cambio de fondo y el relleno de todos los bloques mediante dos mecanismos compartidos: un campo personalizado y un helper PHP.

El campo de sección

Cree una definición de campo compartida a la que pueda hacer referencia cada bloque:

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

Este campo aparece en la pestaña «Sección» del inspector de cada bloque. Los clientes disponen de dos controles: activar un fondo de acento y quitar el relleno inferior (útil para apilar secciones sin espacios).

El helper de sección

En functions.php, cree un helper que convierta estos atributos en clases 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 );
}

La plantilla de cada bloque llama a este helper en su primera línea. El helper devuelve dos cadenas de clases: una para el elemento exterior <section> y otra para el contenedor interior <div>.

Filtro de configuración de Tailwind

También en functions.php, añada el filtro que proporciona su style.css al procesador 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 '';
	}
);

Esto indica a Blockstudio que use su style.css como fuente de configuración de Tailwind v4. Sin esto, los tokens @theme y las definiciones @utility no estarían disponibles en las plantillas de bloques.

Su primer bloque: sección principal

Una sección principal ilustra el patrón completo de un bloque. Empiece con el 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" }
						]
					}
				]
			}
		]
	}
}

Patrones clave que conviene observar:

El contenedor tabs crea un inspector con dos pestañas: «Contenido» para los campos del bloque y «Sección» para los controles compartidos de sección. Todos los bloques usan esta estructura.

Los campos se organizan en contenedores group. Los grupos separan visualmente los campos relacionados en el inspector. El primer grupo contiene campos de texto y el segundo, campos de enlace.

Los valores predeterminados proporcionan contenido útil para que el bloque se vea completo en cuanto se inserta. Esto es fundamental al componer páginas, ya que los bloques se añaden sin que el usuario tenga que interactuar con ellos.

Ahora, la plantilla:

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>

La plantilla sigue un patrón uniforme:

  1. Llame al helper de sección para obtener las clases CSS
  2. <section> exterior con useBlockProps y las clases de sección
  3. <div> interior con clases de contenedor
  4. Contenido renderizado desde $a (la forma abreviada de los atributos)
  5. Renderizado condicional para campos opcionales
  6. Escape correcto: esc_html() para texto, esc_url() para URL y esc_attr() para atributos

Añadir repetidores: cuadrícula de características

Los repetidores permiten a los clientes añadir, quitar y reordenar elementos. Una cuadrícula de características es el ejemplo clásico:

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

La propiedad textMinimized controla el texto que se muestra cuando se contrae una fila del repetidor. Lee el valor del campo title y, si está vacío, usa «Característica». Así, el inspector sigue siendo fácil de usar aunque haya muchos elementos.

El array default proporciona los elementos iniciales. Aparecen cuando se inserta el bloque por primera vez. Proporcione siempre valores predeterminados realistas para que el bloque se vea completo de inmediato.

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>

Los elementos del repetidor se acceden como un array PHP simple. Use foreach para iterar y acceda a los campos de cada elemento mediante su id.

Imágenes y marcadores de posición

Para los bloques con imágenes, use el tipo de campo files y el componente MediaPlaceholder. El marcador de posición muestra una zona para arrastrar y soltar en el editor:

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

En la plantilla, renderice la imagen con wp_get_attachment_image() y muestre un SVG de marcador de posición si no se ha seleccionado ninguna imagen:

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() devuelve un SVG en línea que usa currentColor con la variable --color-accent, por lo que se adapta automáticamente al tema. Para temas claros, use blockstudio_placeholder_light(). Ambos aceptan un argumento de variante:

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

Componer páginas

Las páginas combinan bloques para crear diseños completos mediante la sintaxis <block>. Cree una página de inicio:

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>

Eso es todo. Cada elemento <block> inserta el bloque con sus valores de atributo predeterminados. Ejecute wp bs pages sync para aplicar el contenido de la página a WordPress.

Para anular los valores predeterminados de una página concreta, pase los atributos directamente:

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

Con templateLock establecido en "all", los clientes no pueden añadir, quitar ni reordenar bloques. La estructura de la página queda fijada en la plantilla. Consulte Páginas para ver otros modos de bloqueo y controles de edición.

Ampliar la biblioteca

Una biblioteca mínima empieza con 3-5 bloques. Una biblioteca completa tiene 8-14. Estos son los tipos de bloque más habituales, aproximadamente en orden de frecuencia:

Bloque Descripción Campos principales
Sección principal Título grande con llamadas a la acción título, descripción, enlaces
Características Cuadrícula de ventajas título, repetidor con título + descripción
Llamada a la acción Banner de llamada a la acción título, descripción, enlace
Precios Comparación de planes título, repetidor con nombre + precio + características
Testimonios Citas de clientes repetidor con cita + nombre + cargo
Preguntas frecuentes Acordeón de preguntas título, repetidor con pregunta + respuesta
Logotipos Mosaico de logotipos de clientes título (los logotipos suelen ser SVG codificados directamente)
Contenido Filas alternas de texto e imagen repetidor con título + descripción + imagen
Muestra Imagen a todo lo ancho con pie título, descripción, imagen
Equipo Cuadrícula de integrantes del equipo título, repetidor con nombre + cargo + imagen
Estadísticas Métricas clave repetidor con número + etiqueta

Todos los bloques siguen el mismo patrón: pestañas (Contenido + Sección), grupos para organizar, repetidores para listas y el helper de sección para mantener un espaciado uniforme. Después de crear dos o tres bloques, añadir más se vuelve mecánico.

Añadir más páginas

A medida que crezca la biblioteca, componga distintas páginas a partir de los mismos bloques:

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>

Los mismos bloques sirven para varias páginas, cada una con valores predeterminados distintos. Esa es la ventaja del enfoque de biblioteca: cree los bloques una sola vez y combínelos en tantas páginas como necesite.

Próximos pasos