WebBlocks CMS Inventario para la creación de páginas con IA
Propósito
Este es el contrato de creación y diseño compacto orientado a la IA para WebBlocks CMS. Léelo antes de proponer o aplicar un diseño de página a través del Internal Content API.
Responde cinco preguntas para cada bloque central enviado:
- ¿Qué contenido permanece editable en el administrador del CMS?
- ¿Qué configuraciones y variantes compartidas son compatibles?
- ¿Qué relaciones secundarias y de medios son válidas?
- ¿Qué público estable HTML emite el renderizador?
- ¿Qué resultado visual puede producir el bloque sin página sin formato HTML?
Este documento resume el comportamiento respaldado por el código fuente. El descubrimiento de Live API sigue teniendo autoridad para ID específicos de instalación, complementos habilitados, tipos de bloques personalizados, configuraciones regionales, diseños, registros multimedia, menús de navegación y capacidades.
Línea base de auditoría
- Repositorio:
fklavyenet/webblocks-cms - Sucursal:
main - Confirmación auditada:
741a44bc0fe00bf38cae0753bd9edb02978b0dbe - Documentación de versión auditada:
1.40.2 - Fecha de auditoría:
2026-07-14 - Forma del repositorio: paquete Composer de solo paquete
- Filas del catálogo principal publicadas:
51 - Borrador de filas del catálogo heredado:
7 - Filas principales estructuradas que pueden escribirse mediante IA después de que se aplique la siguiente política:
50 - Filas HTML sin formato grabables por IA después de que se aplique la siguiente política:
0
Modificaciones desde la auditoría
La línea de base anterior sigue siendo la última auditoría completa. Estas entradas fueron corregidas.
contra la fuente después en lugar de volver a auditar cada bloque, así que trate cualquier cosa
fuera de esta lista como 1.40.2-era y confírmelo mediante el descubrimiento de API en vivo.
card(1.40.5): existe el estilo de Tarjetavariant. Este documento anteriormente indicó que no existía ningún campo de variante visual de tarjeta compatible, lo cual era incorrecto desde1.40.5en adelante.link-list(1.40.10):settings.row_layoutysettings.list_frame.link-list-item(1.40.8): miniatura opcional demedia_id.1.91.0: relaciones opcionales de imágenes móviles en ocho bloques de medios nativos.1.91.1: las nueve posiciones de contenido de diapositivas y controles deslizantes.1.93.0: deshacer/rehacer texto enriquecido, modo de enfoque, recuento de palabras y comportamiento de pegado seguro.1.94.0–1.94.2: validación de inicio de complemento administrado, cuarentena, paquetes retenidos y comprobaciones de recuperación de cuentas activas.
H Nota sobre el repositorio histórico: el árbol CMS previo al paquete contenía docs/feature-inventory.md, una amplia matriz de descubrimiento de características del producto. Se eliminó cuando se construyó el árbol del repositorio de solo paquetes y no era un inventario de creación de IA por bloque. El contrato de ejecución ahora se encuentra en resources/contracts/inventory.md.
Familias de fuentes inspeccionadas:
src/Support/Blocks/CoreBlockTypeCatalogSyncer.phpsrc/Support/BlockTypes/BlockTypeContractRegistry.phpsrc/Support/Blocks/BlockTranslationRegistry.phpsrc/Models/Block.phpsrc/Http/Requests/Admin/BlockRequest.phpsrc/Support/InternalContentApi/InternalContentPlanService.phpsrc/Support/InternalContentApi/InternalContentApiOperations.phpsrc/Http/Controllers/InternalContentApi/InternalContentResourceController.phpsrc/Http/Controllers/InternalContentApi/InternalSharedSlotController.phpsrc/Http/Controllers/InternalContentApi/InternalApiDiscoveryController.phproutes/admin.phpresources/views/admin/blocks/types/*.blade.phpresources/views/admin/blocks/settings/*.blade.phpresources/views/pages/partials/blocks/*.blade.phppublic/cms/css/public.css- Pruebas de paquetes enfocadas y documentación actual del producto
Reglas de creación de IA no negociables
- Usa utilizar bloques estructurados. No almacene una página, sección, colección de tarjetas, shell de navegación, formulario o componente visual en Trusted HTML.
htmles una trampilla de escape exclusiva para humanos. El descubrimiento de API puede identificarlo como no disponible, pero ninguna mutación de API puede crear, actualizar, reemplazar, mover, reordenar, clonar, promover, publicar o eliminar un bloque HTML.- No omita la restricción HTML mediante texto enriquecido,
<style>,<script>, atributos de controlador de eventos, marcado de iframe, marcado SVG, marcado codificado o configuraciones inventadas. - Use solo campos, valores de enumeración, roles de medios y relaciones secundarias documentados aquí y confirmados mediante descubrimiento en vivo.
- Trate un campo editable por el administrador como parte del contrato de creación admitido. Un valor reconocido únicamente por un renderizador o una ruta de compatibilidad heredada no es un campo de creación de IA normal.
- Si una región visual no se puede expresar con el contrato admitido, deténgase e informe una brecha de capacidad. No lo aproximes silenciosamente con bloques no relacionados y no recurras a HTML.
- El sitio CSS puede refinar la tipografía, el espaciado, el color, los bordes, las sombras y la presentación responsiva a través de ganchos públicos estables. No debe convertirse en un almacén de contenido oculto ni reconstruir el marcado semántico faltante.
- No apunte a los ID de bases de datos, ID de bloques generados, selectores de posición de hermanos ni a
:nth-child()para el comportamiento de diseño esencial. Prefiere atributos de tipo bloque, clases nativaswb-*, clases de cuerpo de página y configuraciones documentadas. - Mantenga todos los títulos, párrafos, etiquetas, botones, insignias, imágenes, subtítulos, menús y configuraciones de formulario visibles editables a través de su campo CMS nativo o registro relacionado.
- Validar primero, aplicar solo después de la aprobación explícita del usuario, crear borradores primero y dejar las acciones de actualización del sistema en vivo y las pruebas visuales en vivo al operador humano a menos que se autorice por separado.
- Trate la tarjeta como una presentación voluntaria, no como la forma predeterminada de copiar una copia relacionada con el grupo. Utilice una Tarjeta solo para una entidad limitada, repetible o procesable de forma independiente, como un producto, complemento, plan de precios, descarga o formulario.
- Antes de elegir bloques, indique una dirección de diseño a nivel de sitio que cubra carácter, densidad, tipografía, geometría, imágenes, esquinas y contraste. Haga que el árbol de bloques y el sitio CSS implementen esa dirección en lugar de elegir cada sección de forma aislada.
- Variar el ritmo de la página deliberadamente. Combine regiones estrechas, regulares, anchas y de ancho completo; copia silenciosa alternativa, imágenes dominantes y colecciones estructuradas en lugar de repetir secciones con el mismo peso.
HTML Política de API de bloqueo
El contrato del producto de destino es:
| Superficie | Comportamiento html |
|---|---|
| Administrador de CMS | Los operadores humanos pueden crear y editar el Trusted HTML revisado. |
| Renderizador público | Los bloques HTML publicados existentes continúan renderizándose. |
| Descubrimiento de API | Reporte el bloqueo como api_readable: true, api_writable: false, authoring: human_only y explique la restricción. No presente un ejemplo de carga útil grabable. |
| Validar/aplicar contenido | Rechace cada carga útil html nueva o de reemplazo con el código estable block_type_not_api_writable. |
| Creación incremental de página/bloque de espacio compartido | Rechazar html antes de la normalización o persistencia. |
| Bloque existente PATCH | Rechazar cuando el tipo de bloque de destino sea html, incluso si el campo enviado se consideraría seguro. |
| Reordenar, mover, eliminar, reemplazar espacios, actualizar por etapas y promocionar | Rechace cualquier mutación cuyo subárbol afectado o alcance de reemplazo contenga un bloque HTML existente. No lo elimines como efecto secundario. |
| Capacidades de token API | Ninguna capacidad puede anular la restricción a nivel de producto. |
| Leer puntos finales | Puede devolver el bloque existente para su inspección de acuerdo con la política de lectura elegida; El acceso de lectura nunca debe implicar acceso de escritura. |
Esta política se aplica en el código mediante una única clase de política de producto, WebBlocks\Cms\Support\BlockTypes\BlockTypeApiAuthoringPolicy. Cada superficie API la consulta en lugar de repetir la regla: ambos normalizadores de bloques, PATCH de bloques existentes, creación incremental de páginas y Shared Slot, reordenamiento de páginas/Shared Slot, eliminación de subárbol, borrado total de Shared Slot, publicación de páginas y Shared Slot, reemplazo de ranuras de borrador, creación y promoción de actualizaciones por etapas, asignación de Shared Slot y eliminación de páginas API. Los rechazos ocurren antes de cualquier transacción o escritura, devuelven HTTP 422 con el código estable block_type_not_api_writable y no dejan cambios parciales. Ninguna capacidad de token lo anula.
Qué significa "admisible por CMS"
Un diseño es manejable por CMS solo cuando se cumple todo lo siguiente:
- El contenido visible se almacena en campos de traducción nativos, configuraciones, relaciones de biblioteca multimedia, registros de navegación, registros comerciales o bloques secundarios.
- El editor de bloques normal expone los campos necesarios para mantener el resultado.
- El marcado público proviene de un renderizador de paquete o complemento, no del contenido de la página.
- La presentación utiliza variantes documentadas, configuraciones, tokens de tema y ganchos CSS estables.
- Reordenar o editar contenido no requiere editar HTML o CSS.
- El comportamiento móvil proviene del renderizador, WebBlocks UI, o del sitio estable CSS, en lugar de marcas móviles duplicadas en el contenido.
Un renderizador puede reconocer un valor interno o heredado que el formulario de administración normal no expone. Dicho valor se documenta como una entrada de compatibilidad, no como un campo de creación de IA recomendado.
Tabla de decisiones de diseño
| Necesidad visual | Contrato preferente | Condición de parada |
|---|---|---|
| Banda de página principal | section con bloques secundarios | No coloque una copia visible en la configuración de la sección. |
| Restricción de ancho | container | No utilice el contenedor como tarjeta o superficie. |
| Ritmo de contenido vertical | stack | No utilice el contenedor sólo para obtener flujo vertical. |
| Contenido principal más una acción o valor compacto | split | Utilice exactamente dos hijos directos; Nest Stack cuando un lado necesita varios bloques. |
| Acciones horizontales o elementos compactos | cluster | No utilice Grid para una sola fila de botones. |
| Células repetidas receptivas | grid con hijos estructurados | No utilice Grid para falsificar una tabla semántica. |
| Título de la página, introducción, insignia, icono, metadatos | content_header | Siempre posee un H1; no lo utilice para encabezados anidados normales. |
| Introducción a la comercialización | hero | Hero admite diseños a la izquierda, centrado, dividido y sin sangrado; La división reproduce los medios en primer plano, mientras que el sangrado completo crea una banda fotográfica sin marco. Informe un espacio cuando el diseño requiera una segunda imagen de primer plano editable o contenido anidado arbitrario. |
| Banda de conversión | cta | La CTA actual no acepta elementos secundarios estructurados normales que no sean elementos secundarios de botones heredados administrados. |
| Elementos repetidos de características o estadísticas | columns y column_item | Prefiera grid y card componible cuando se necesita contenido anidado arbitrario. |
| Tarjeta componible | card plus Regiones de tarjetas | Úselo solo para contenido delimitado/accionable de forma independiente; Las variantes son predeterminadas, planas, silenciadas, resaltadas y acentuadas. |
| Imagen semántica única | image | Utilice la Galería para colecciones y campos multimedia de fondo para fondos compatibles. |
| Colección de imágenes | gallery | No agregue una caja de luz HTML separada. |
| Control deslizante/carrusel | slider más slide | Utilice Galería cuando el contenido sea solo una colección de imágenes. |
| Navegación | Registros de navegación más bloques de barra de navegación/barra lateral | No codifique los anclajes de navegación en HTML. |
| Formulario de contacto | contact_form | No utilice el marcado <form> sin formato o mailto: como formato normal. |
| Calificaciones/comentarios | rating y comments | No reproduzca el almacenamiento de compromiso ni los formularios en HTML. |
| Composición única no admitida | Informe sobre la brecha de capacidad | Nunca establezca de forma predeterminada html. |
Forma del plan de contenido canónico
Utilice matrices children anidadas. No envíe ID de relación de base de datos en un plan de contenido.
{
"type": "section",
"settings": {
"spacing": "lg"
},
"children": [
{
"type": "container",
"settings": {
"width": "lg"
},
"children": [
{
"type": "plain_text",
"translations": {
"content": "Editable copy"
}
}
]
}
]
}
Convenciones del plan de contenido:
- Coloque la copia de propiedad local directamente en
translationspara la configuración regional del plan seleccionada. - Ingrese URL, destino, variante de presentación y otras opciones compartidas en
settings. - Coloque la asignación directa de biblioteca multimedia en
media_id. slide,image,hero,section,card,cta,content_headerylink-list-itemtambién acepta una referencia opcional de nivel superiormobile_media_idun registro de la biblioteca multimedia de imágenes. Se almacena enblock_mediacon rolmobile_image, compartido entre configuraciones regionales y editable a través de los medios de administración selector yPATCH /blocks/{block}. En pantallas de hasta 768 px de ancho reemplaza la imagen predeterminada; una imagen móvil ausente, eliminada o privada vuelve a el valor predeterminado. Envíenullpara borrarlo; omitirlo en PATCH lo conserva. Las imágenes de primer plano utilizan<picture><source media="(max-width: 768px)">; Los bloques de fondo utilizan un fondo responsivo CSS. Utilice otro cultivo de la mismo objeto visual: el texto alternativo, los subtítulos, la posición, el ajuste, las superposiciones y los enlaces permanecen compartido. El Visor de galería del bloque de imágenes continúa abriendo la configuración predeterminada imagen de resolución completa. Los elementos de la galería, los logotipos de marcas, los vídeos y el audio no aceptar este campo.- Colocar elementos de la galería en
gallery_itemsogallery_media_ids. - Uuse solo
childrenanidado; no envíeid,parent_id,block_id,slot_type_idoblock_type_id. - La API actualmente acepta un objeto
settingsde forma amplia. Esa permisividad no es permiso para inventar escenarios; utilice únicamente las claves que se enumeran a continuación.
Shell de representación pública
La representación normal de la ranura principal proporciona:
<main class="wb-public-main" id="main-content">
<div class="wb-container wb-container-lg">
<div class="wb-stack wb-gap-6">
<!-- page blocks -->
</div>
</div>
</main>
Los bloques marcados como root-owner colocan data-wb-public-block-type en su propia raíz semántica. Otros bloques de nivel superior normalmente reciben:
<div class="wb-public-block" data-wb-public-block-type="block-handle">
<!-- renderer output -->
</div>
Los guiones bajos se normalizan a guiones en data-wb-public-block-type; por ejemplo content_header se convierte en content-header.
Índice de catálogo rápido
El catálogo principal publicado actualmente contiene 55 filas:
| Grupo | Manijas |
|---|---|
| Diseño y composición | section, container, stack, split, cluster, grid, card, card_header, card_body, card_footer, slider, slide |
| Editorial y marketing | header, plain_text, rich-text, content_header, hero, cta, columns, column_item, feature-grid, feature-item, stat-card, image, gallery, download, file, video, audio, code, button_link, table, quote, page-list, application |
| Navegación | link-list, link-list-item, navigation-auto, toc, breadcrumb, header-actions, sticky-navbar, navbar-brand, navbar-navigation, sidebar-brand, sidebar-navigation, sidebar-nav-item, sidebar-nav-group, search-form, sidebar-footer |
| Patrón, forma y compromiso | alert, contact_form, rating, comments |
| Avanzado sólo para humanos | HTML |
Bloques de diseño y composición
section — Sección
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Banda de páginas semántica principal y agrupación secundaria. |
| Contenido editable por el administrador | Ninguna copia visible. El settings.layout_name opcional es solo metadatos del editor. |
| Configuración | spacing: empty, sm, lg; flow: normal, offset-up, overlap-previous; fondo opcional media_id; background_position: center, top, bottom, left, right; background_overlay: soft, medium, strong, none. |
| Niños | Cualquier tipo de hijo publicado admitido; Los planes API requieren al menos un niño renderizable. |
| HTML | <section class="wb-section [wb-section-sm or wb-section-lg] [wb-public-section--offset-up or wb-public-section--overlap-previous] wb-stack" data-wb-public-block-type="section">…</section> propietario de la raíz. Los medios de fondo agregan ganchos de clase/estilo propiedad del paquete. Los modificadores de flujo se reinician en pantallas pequeñas. |
| Aspecto de ejemplo | Una banda temática de ancho completo que contiene un Contenedor restringido, o una banda desplazada deliberadamente que rompe el ritmo vertical uniforme. |
| Evitar | Texto visible en la configuración, cromo vacío, uso de la Sección como tarjeta o superposición de varias secciones consecutivas. |
container — Recipiente
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Restricción de ancho y flujo secundario opcional. |
| Contenido editable por el administrador | Ninguna copia visible; layout_name opcional solo para editor. |
| Configuración | width: empty, sm, md, lg, xl, full; flow: stack or none. |
| Niños | Cualquier tipo de hijo publicado admitido; al menos un niño requerido por los planes API. |
| HTML | <div class="wb-container [wb-container-*] [optional wb-stack]" data-wb-public-block-type="container">…</div> propietario de raíz; wb-stack requiere flow: stack explícito. |
| Aspecto de ejemplo | Contenido de página centrado con un ancho máximo; el valor predeterminado neutral se compone directamente con un clúster dentro de la barra de navegación. |
| Evitar | Tratar el ancho como una superficie, una tarjeta o una función temática. |
stack — Pila
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Flujo vertical y ritmo constante entre bloques infantiles directos. |
| Contenido editable por el administrador | Ninguna copia visible; layout_name opcional solo para editor. |
| Configuración | spacing: empty/default, 1, 2, 3, 4, 6, 8. |
| Niños | Cualquier tipo de hijo publicado admitido; al menos un niño requerido por los planes API. |
| HTML | <div class="wb-stack [wb-stack-{n}]" data-wb-public-block-type="stack">…</div> propietario de la raíz. |
| Aspecto de ejemplo | El nombre del producto, la descripción y la nota de respaldo organizados de arriba a abajo. |
| Evitar | Control de ancho de página, acciones horizontales o columnas iguales. |
split — Dividir
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Composición de dos caras donde el primer niño crece y el segundo se queda en tamaño contenido. |
| Contenido editable por el administrador | Ninguna copia visible; layout_name opcional solo para editor. |
| Configuración | gap: empty/default, 0, 1, 2, 3, 4, 6, 8; items_alignment: center/default, start, end, stretch; width: auto/default or full; responsive: stack or preserve. New admin/API blocks default to stack while existing empty settings preserve the legacy row. |
| Niños | Exactamente dos hijos directos. Coloque una pila dentro de cada lado cuando ese lado necesite varios bloques. |
| HTML | <div class="wb-split …" data-wb-public-block-type="split">…</div> propietario de raíz con clases wb-* incluidas en la lista permitida. La pila responsiva agrega .wb-public-split--stack-mobile propiedad del paquete y cambia a una columna de ancho completo a 48rem y menos. |
| Aspecto de ejemplo | Identidad del producto a la izquierda y precio más acción de compra a la derecha. |
| Evitar | Columnas iguales repetidas, grupos de botones envolventes o más de dos hijos directos. |
cluster — Grupo
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Composición horizontal o en línea, especialmente acciones y elementos internos de la barra de navegación. |
| Contenido editable por el administrador | Ninguna copia visible; layout_name opcional solo para editor. |
| Configuración | gap: empty, none, xs, sm, md, lg; alignment: start/default, center, end, between; items_alignment: center/default, start, end, stretch; wrap: wrap/default or nowrap; width: auto/default or full. |
| Niños | Cualquier tipo de hijo publicado admitido; al menos un niño requerido por los planes API. |
| HTML | <div class="wb-cluster …" data-wb-public-block-type="cluster">…</div> propietario de raíz con clases wb-* incluidas en la lista permitida. |
| Aspecto de ejemplo | Una fila de CTA responsiva de dos botones o una fila de marca/navegación/acciones. |
| Evitar | Grandes cuadrículas de tarjetas repetidas. |
grid — Red
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Diseño responsivo de varias columnas. |
| Contenido editable por el administrador | Ninguna copia visible; layout_name opcional solo para editor. |
| Configuración | columns: 2, 3, 4; ratio: equal, lead-left, lead-right (asymmetric ratios apply only to two columns); gap: empty, 3, 4, 6; alternate_media_text_sections: boolean; alternate_start: media_left or text_left. |
| Niños | Cualquier tipo de hijo publicado admitido; al menos un niño requerido por los planes API. |
| HTML | <div class="wb-grid wb-grid-{n} [wb-gap-{n}] [wb-public-grid--lead-*]" data-wb-public-block-type="grid">…</div> propietario de la raíz. Las proporciones de clientes potenciales se representan como 2:1 o 1:2 por encima del punto de interrupción móvil normal de una columna. El modo alterno puede cambiar el orden de los hijos directos sin cambiar la raíz. |
| Aspecto de ejemplo | Tres bloques de tarjetas en una fila de funciones, o grupos de imágenes/contenido emparejados que se alternan de izquierda a derecha. |
| Evitar | Tablas semánticas o una fila de acciones compacta. |
card — Tarjeta
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Superficie enmarcada componible. |
| Contenido editable por el administrador | No hay copia principal visible normal; layout_name opcional solo para editor. Es posible que las filas de tarjetas heredadas sin región aún muestren copias antiguas. |
| Configuración | Estilo de tarjeta opcional en la columna variant compartida: flat, muted, highlight, accent; un variant vacío representa la tarjeta predeterminada. Imagen de fondo opcional media_id, background_position, background_overlay. Los url y target opcionales hacen que toda la Tarjeta componible sea un enlace semántico. |
| Niños | Niños directos restringidos a card_header, card_body, card_footer; al menos un niño requerido por los planes API. |
| HTML | <article class="wb-card">…</article> de propiedad raíz o <a class="wb-card wb-no-decoration">…</a> cuando se configura una URL de tarjeta completa. Las Tarjetas vinculadas no deben contener controles interactivos anidados. |
| Aspecto de ejemplo | Encabezado de imagen o ícono, contenido del cuerpo editable y pie de página de acción dentro de un shell de tarjeta nativo. |
| Evitar | Tarjetas anidadas dentro de Tarjetas o que utilizan una copia principal heredada para contenido nuevo. |
card_header — Encabezado de tarjeta
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Región del encabezado dentro de la Tarjeta. |
| Contenido editable por el administrador | Sin copia directa; Los bloques secundarios contienen contenido. Editor opcional layout_name solo. |
| Configuración | icon_slug del catálogo de íconos de contenido activo; icon_tone: default, soft, brand, accent, highlight, bold, quiet; icon_size: default, sm, lg, xl. |
| Niños | Contenido estructurado infantil. No anide bloques de región de tarjeta. La ubicación normal está directamente debajo de Tarjeta. |
| HTML | <div class="wb-card-header" data-wb-public-block-type="card-header">[icon]…</div> propietario de la raíz. |
| Aspecto de ejemplo | Fila de título de tarjeta con un icono de catálogo y encabezado/texto sin formato anidados. |
| Evitar | Colocación fuera de la Tarjeta. |
card_body — Cuerpo de la tarjeta
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Región de contenido principal dentro de la tarjeta. |
| Contenido editable por el administrador | Sin copia directa; Los bloques secundarios contienen contenido. Editor opcional layout_name solo. |
| Configuración | No hay configuración visual pública más allá de layout_name solo para editor. |
| Niños | Contenido estructurado infantil; Los planes API requieren al menos uno. No anide bloques de región de tarjeta. |
| HTML | Propiedad de raíz <div class="wb-card-body" data-wb-public-block-type="card-body">…</div>. |
| Aspecto de ejemplo | Copia de tarjeta, imagen, texto enriquecido o un pequeño grupo de botones. |
| Evitar | Colocación fuera de la Tarjeta. |
card_footer — Pie de página de tarjeta
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Región de apoyo o acción dentro de la Tarjeta. |
| Contenido editable por el administrador | Sin copia directa; Los bloques secundarios contienen contenido. Editor opcional layout_name solo. |
| Configuración | No hay configuración visual pública más allá de layout_name solo para editor. |
| Niños | Contenido estructurado infantil; Los planes API requieren al menos uno. No anide bloques de región de tarjeta. |
| HTML | Propiedad de raíz <div class="wb-card-footer" data-wb-public-block-type="card-footer">…</div>. |
| Aspecto de ejemplo | Uno o dos hijos de Button Link alineados por un clúster anidado. |
| Evitar | Colocación fuera de la Tarjeta. |
slider — Control deslizante
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Carrusel componible que llena el contenedor colocado. |
| Contenido editable por el administrador | No hay copia principal visible; layout_name opcional solo para editor. |
| Configuración | height: auto, fill, viewport, large, medium, small, custom; opcional min_height; aspect_ratio: 16/9, 4/3, 1/1; interval_ms: 1000–30000; valores booleanos autoplay, pause_on_hover, show_arrows, show_dots, loop, swipe, keyboard; overlay: none/default, soft, medium, dark, strong; content_position: center/default, center-left, center-right, top-left, top-center, top-right, bottom-left, bottom-center, bottom-right; content_width: medium/default, narrow, wide, full; text_color: auto/default, light, dark; background_fit: cover/default or contain. Transition is currently normalized to slide. |
| Niños | Sólo slide; Se requiere al menos una diapositiva. |
| HTML | <section class="wb-slider …" data-wb-slider data-wb-public-block-type="slider"> de propiedad raíz con ventana gráfica, seguimiento, flechas y puntos opcionales. |
| Aspecto de ejemplo | Carrusel de héroes de ancho completo, control deslizante con tarjetas o paneles multimedia de fondo con contenido infantil editable. |
| Evitar | Galerías de imágenes estáticas. |
slide — Deslizar
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Propósito | Un panel dentro del control deslizante. |
| Contenido editable por el administrador | Ninguna copia visible directa; layout_name opcional de solo editor y aria_label compartido. |
| Configuración | Imagen de fondo media_id; background_position; background_overlay (none, soft, medium, strong: cada uno representa una malla distinta desde WebBlocks UI 2.22.0; antes de eso, medium colapsó en strong); content_position: center/default, center-left, center-right, top-left, top-center, top-right, bottom-left, bottom-center, bottom-right; content_width; text_color; background_fit. |
| Niños | Cualquier tipo de hijo estructurado admitido; Se permite una diapositiva solo de fondo. El padre normal es Slider. |
| HTML | <article class="wb-slide …" data-wb-public-block-type="slide">[img.wb-slide-media]<div class="wb-slide-content">…</div></article> propietario de la raíz. |
| Aspecto de ejemplo | Fotografía de fondo del producto con contenido de encabezado anidado, texto sin formato y enlace de botón. |
| Evitar | Uso independiente de nivel superior cuando no se pretende una semántica de carrusel. |
Bloques editoriales y de marketing
header — Encabezamiento
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title. |
| Configuraciones y variantes | settings.variant: h1–h6; alignment: left, center, right; anchor: safe same-page ID. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Propiedad raíz del <h1> al <h6> con clase de alineación opcional y id. |
| Aspecto de ejemplo | Encabezado de sección semántica que puede ser indexado por TOC. |
| Evitar | Introducción de página con metadatos; utilice el encabezado de contenido. |
plain_text — Texto sin formato
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.content como texto sin formato escapado. |
| Configuraciones y variantes | alignment: left, center, right. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más <p class="[wb-text-*]">…</p>. |
| Aspecto de ejemplo | Párrafo corto, etiqueta u oración de apoyo. |
| Evitar | Listas, enlaces, encabezados o texto del cuerpo formateado. |
rich-text — Texto enriquecido
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.content a través del editor y desinfectante de texto enriquecido seguro; El historial del editor admite deshacer/rehacer, con un contador de palabras y un modo de enfoque opcional. |
| Configuraciones y variantes | Ninguno. Se eliminan los formatos, atributos y clases no admitidos; Los encabezados y celdas de tabla pegados conservan su texto como párrafos y se elimina el marcado de archivos ejecutables/medios. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más <div class="wb-rich-text">[sanitized editorial markup]</div>. |
| Aspecto de ejemplo | Varios párrafos con énfasis en línea seguro, enlaces y listas simples. |
| Evitar | Marcado de diseño, <style>, scripts, iframes, formularios, botones, tablas o una página completa. |
content_header — Encabezado de contenido
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle como introducción, translations.eyebrow como etiqueta de insignia opcional, translations.meta como elementos de metadatos. |
| Configuraciones y variantes | alignment: left, center, right; icon_slug; icon_tone; icon_size: default, sm, lg, xl; badge_tone: neutral, info, success, warning, danger; configuración opcional de imagen de fondo y superposición. |
| Niños/medios de comunicación | Sin hijos; La imagen directa media_id es un medio de fondo. |
| HTML | <header class="wb-content-header …"> de propiedad raíz con grupo de iconos/insignias opcionales, <h1 class="wb-content-title"> fijo, subtítulo y fila de metadatos. |
| Aspecto de ejemplo | Título de la página con insignia/icono de producto opcional, texto principal conciso y dos etiquetas de metadatos. |
| Evitar | Secciones anidadas donde H1 es semánticamente incorrecto. |
hero — Héroe
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle como ceja, translations.content. Los botones de acción son bloques secundarios button_link independientes con su propio formulario de administración. |
| Configuraciones y variantes | variant: default, muted, soft, accent; layout: left, centered, split, or full-bleed; title_tag: h1, h2, h3; configuración opcional de imagen de fondo y superposición. |
| Niños/medios de comunicación | Las acciones son bloques secundarios button_link, sin un recuento fijo. En diseños a la izquierda/centrado/sangrado completo, media_id es material de fondo; en división, se muestra como una imagen de primer plano al lado de la copia. |
| HTML | Los diseños heredados poseen <section class="wb-card wb-promo [wb-card-*]">; La división agrega .wb-promo--split y .wb-promo-media. El sangrado completo elimina deliberadamente la clase de tarjeta y utiliza .wb-public-hero--full-bleed con un .wb-public-hero__copy alineado. |
| Aspecto de ejemplo | Una promoción contenida, una imagen en primer plano/copia dividida o un héroe fotográfico sin marco en toda la ventana gráfica, además de acciones. |
| Limitación dura | Sin segunda imagen de primer plano, precio del producto/zona de confianza ni contenido anidado arbitrario. |
| Acciones | Agregue niños button_link; se renderizan dentro de .wb-promo-actions. Los objetos primary_cta / secondary_cta {label, url} siguen siendo aceptados como una taquigrafía que escribe los dos primeros de esos hijos. No busque un clúster hermano con enlace de botón, que se muestra fuera de la raíz de la promoción. allowed_child_handles también enumera el button heredado, que no tiene una fila de catálogo publicada y permanece en unreachable_child_handles. |
cta — llamada a la acción
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle como ceja, translations.content. Los botones de acción son bloques secundarios button_link independientes con su propio formulario de administración. |
| Configuraciones y variantes | variant: default, muted, soft, accent; configuración opcional de imagen de fondo y superposición. El título de la CTA se muestra como H2. |
| Niños/medios de comunicación | Las acciones son bloques secundarios button_link, sin recuento fijo; La imagen directa media_id es un medio de fondo. |
| HTML | <section class="wb-card wb-promo [wb-card-*]"> propietario de raíz con .wb-promo-copy y fila de acción opcional. |
| Aspecto de ejemplo | Banda de conversión corta cerca del final de una página. |
| Acciones | Idéntico a Hero: agregue hijos button_link o use la taquigrafía primary_cta / secondary_cta. |
| Limitación | settings.layout=centered es compatible con el renderizador, pero no está expuesto en el formulario de administración de CTA normal y no es un campo de creación de IA recomendado. |
columns — columnas
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle, translations.content; título del elemento secundario, insignia, contenido, URL, icono y tonos. |
| Configuraciones y variantes | settings.variant: cards, plain, stats. New Internal Content API plans default an omitted variant to plain; cards debe ser deliberado. Los bloques almacenados existentes con una variante vacía conservan el respaldo del renderizador cards heredado. |
| Niños/medios de comunicación | Sólo column_item. El recuento de niños selecciona el diseño de pila, 2 columnas, 3 columnas o 4 columnas. |
| HTML | <section class="wb-stack wb-gap-4"> de propiedad raíz con introducción opcional y una cuadrícula de elementos responsiva. |
| Aspecto de ejemplo | Tres tarjetas de beneficios, cuatro funciones compactas o una fila métrica simple. |
| Advertencia de manejabilidad | El procesador de estadísticas puede utilizar el subtitle secundario como valor, pero los formularios de administración de elementos de columna normales no exponen ese subtitle. Las estadísticas creadas por IA que dependen de ella no son completamente manejables y deben evitarse hasta que el contrato de formulario esté alineado. |
column_item — Elemento de columna
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.content, insignia translations.eyebrow opcional; compartido settings.url, icon_slug, icon_tone, icon_size, badge_tone. |
| Configuraciones y variantes | La presentación está controlada por la variante de Columnas principal: tarjetas, simples o estadísticas. |
| Niños/medios de comunicación | Ninguno; destinado únicamente en Columnas. |
| HTML | Tarjetas: .wb-card > .wb-card-body; plain: .wb-icon-card; stats: .wb-stat. Optional safe link wraps cards/plain output. |
| Aspecto de ejemplo | Tarjeta de función de icono y copia con una insignia opcional. |
| Evitar | Uso independiente o basado en subtítulos de solo renderizador para un valor de estadística. |
Use plain para cualidades, principios, beneficios, resúmenes de procesos y otra copia que no represente objetos independientes. Utilice cards solo cuando cada elemento tenga un límite significativo propio. La cantidad de elementos, especialmente el conocido conjunto de tres, nunca es por sí sola una razón para elegir tarjetas.
feature-grid — Cuadrícula de funciones
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, subtitle, content; campos de funciones secundarias. |
| Configuraciones y variantes | Ninguna variante de presentación independiente. El renderizador fuerza la presentación de las tarjetas de Columnas y prefiere tres columnas. |
| Niños/medios de comunicación | feature-item y compatibilidad column_item. |
| HTML | Delega a columnas y representa una cuadrícula de tarjetas. Block::ownsPublicRoot no lo enumera como propietario de la raíz, por lo que la salida de nivel superior puede recibir un contenedor genérico alrededor de la raíz de la sección delegada. |
| Aspecto de ejemplo | Tarjetas de funciones heredadas de tres en adelante. |
| Recomendación | Para páginas nuevas, prefiera Columnas/Elemento de columna o Cuadrícula/Tarjeta; Utilice Feature Grid solo cuando su editor dedicado sea valioso y se acepte el contrato delegado. |
feature-item — Artículo destacado
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.content, etiqueta de identificación opcional; URL compartida, ícono/tono, tono de insignia. |
| Configuraciones y variantes | Delega siempre en la presentación de tarjetas de Elementos de Columna. |
| Niños/medios de comunicación | Ninguno; previsto en Cuadrícula de funciones. |
| HTML | .wb-card > .wb-card-body > .wb-icon-card with optional icon and badge. |
| Aspecto de ejemplo | Una tarjeta de funciones con íconos. |
| Recomendación | Prefiere regiones de tarjeta canónicas o elementos de columna para nuevas composiciones de uso general. |
stat-card — Tarjeta de estadísticas
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Etiqueta translations.subtitle, valor translations.title, detalle translations.content; URL compartida. |
| Configuraciones y variantes | Ninguno. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Contenedor genérico más .wb-stat, .wb-stat-label, .wb-stat-value, .wb-stat-meta y el enlace opcional Más información. |
| Aspecto de ejemplo | Valor “24h” con etiqueta “Despacho” y detalle de respaldo. |
| Evitar | Tarjeta de marketing decorativa donde se necesita contenido anidado arbitrario. |
image — Imagen
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Imagen de propiedad local alt_text y caption; URL opcional compartida. |
| Configuraciones y variantes | viewer_enabled opta por una imagen no vinculada en el Visor de galería de CMS; viewer_group une bloques de imágenes colocados de forma independiente en un conjunto de visor navegable. El punto focal y las variantes generadas pertenecen al registro de Medios. |
| Niños/medios de comunicación | Imagen directa media_id; sin hijos. |
| HTML | <figure class="wb-stack wb-gap-2"> de propiedad raíz con salida responsiva <img>, imagen vinculada o wb-gallery-trigger opcional y <figcaption>. Los grupos habilitados registran un modal de visor de galería existente bajo la raíz de superposición canónica. |
| Aspecto de ejemplo | Imagen editorial o de producto con título editable. |
| Evitar | Tratamiento de fondo o disposición decorativa HTML. Utilice Galería cuando la colección en sí deba representarse como una cuadrícula; Utilice grupos de espectadores cuando las imágenes compuestas de forma independiente deban compartir un espectador sin cambiar el diseño. |
gallery — Galería
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Artículos de galería pedidos con alt_text, caption, overlay_title, overlay_text de propiedad local; Título de visor compartido opcional. La copia de introducción de la galería está intencionalmente separada. |
| Configuraciones y variantes | variant: grid, masonry, collage; columns: 2–5; gap: none, sm, md, lg; aspect_ratio: auto, square, 4:3, 16:9, portrait; captions_mode: hidden, below, overlay, on-hover; overlay_mode: none, gradient, solid; lightbox_enabled: boolean. |
| Niños/medios de comunicación | Imagen de referencia gallery_items o gallery_media_ids Registros multimedia; No hay niños en bloque. |
| HTML | .wb-gallery.wb-gallery--{variant} de propiedad raíz con elementos de galería, medios responsivos, subtítulos y un visor de propiedad de registro opcional bajo la raíz de superposición canónica. |
| Aspecto de ejemplo | Cuadrícula de productos iguales, mampostería editorial de altura natural o primer collage destacado. |
| Evitar | Agregar encabezado/descripción a la Galería; redacte el encabezado de contenido o el texto enriquecido antes. |
download — Descargar
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Etiqueta del botón translations.title y copia auxiliar translations.subtitle. |
| Configuraciones y variantes | settings.variant: primary, secondary, ghost. |
| Niños/medios de comunicación | Documento directo/otro media_id; sin hijos. |
| HTML | .wb-stack.wb-gap-2 de propiedad raíz con <a class="wb-btn …" download> y un párrafo auxiliar opcional. |
| Aspecto de ejemplo | Botón “Descargar guía” con descripción del archivo. |
| Evitar | Tarjetas de archivo sólo externas; utilizar Archivo. |
file — Archivo
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.content; reserva de URL compartida. |
| Configuraciones y variantes | Ninguno. |
| Niños/medios de comunicación | Documento directo/otro media_id; Los medios ganan a las URL externas seguras. |
| HTML | Tarjeta silenciada de propiedad raíz con título, descripción, botón de descarga/apertura y metadatos del archivo. |
| Aspecto de ejemplo | Tarjeta de recursos en PDF descargable. |
| Evitar | Descargas simples con solo botones. |
— Vídeo
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.content; reserva de URL segura compartida. |
| Configuraciones y variantes | La fuente determina el video nativo, el iframe de YouTube/Vimeo o el botón para abrir video. |
| Niños/medios de comunicación | Vídeo directo media_id; sin hijos. |
| HTML | Tarjeta silenciada de propiedad raíz que contiene <video>, un proveedor en la lista permitida <iframe> o un enlace seguro. |
| Aspecto de ejemplo | Vídeo de demostración subido con título y descripción editables. |
| Evitar | Marco flotante arbitrario HTML. |
audio — Audio
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.content; reserva de URL HTTP segura compartida. |
| Configuraciones y variantes | Ninguno. |
| Niños/medios de comunicación | El administrador y el renderizador admiten medios de audio seleccionados; sin hijos. |
| HTML | Tarjeta silenciada de propiedad raíz con copia y <audio controls> nativo. |
| Aspecto de ejemplo | Lección de audio o reproductor de muestras. |
| Brecha API | La lista de medios permitidos directos del plan de contenido auditado omite el audio, por lo que la asignación media_id se rechaza aunque el administrador y el renderizador la admitan. Utilice una URL segura revisada solo cuando sea apropiado o corrija el contrato de API antes de la asignación de medios de IA. |
code — Código
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, nombre de archivo/etiqueta de idioma translations.subtitle, cuerpo del código translations.content. |
| Configuraciones y variantes | settings.language se vuelve desinfectado data-language. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más <pre><code data-language="…">…</code></pre>. |
| Aspecto de ejemplo | Comando que se puede copiar o fragmento de código fuente. |
| Evitar | Prosa, maquetación o guiones ejecutables. |
button_link — Enlace de botón
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title como etiqueta del botón; compartido settings.url. En el momento de la renderización pública, una ruta interna sigue la configuración regional de renderización (reescrita en la ruta traducida de la página de destino cuando se resuelve); el valor almacenado permanece compartido y sin procesar. |
| Configuraciones y variantes | settings.target: _self or _blank; compartido variant: primario/predeterminado o secundario. La URL acepta una URL HTTP(S) completa segura, una ruta del sitio, un ancla, un destino mailto: o tel:. |
| Niños/medios de comunicación | Ninguno. Esta es una acción editorial independiente y es distinta del hijo button administrado fuera del catálogo utilizado por Hero y CTA. |
| HTML | Envoltura genérica más <a class="wb-btn wb-btn-primary"> o su equivalente de clase secundaria; _blank agrega rel="noopener noreferrer". La URL vacía o insegura no emite ningún ancla. |
| Aspecto de ejemplo | Una acción primaria o secundaria gestionada, o varias acciones ordenadas por un Clúster. |
| Evitar | Anclas codificadas en HTML o sustituyéndolas por la acción secundaria administrada interna de Hero/CTA cuando la acción debe representarse dentro de esa raíz promocional. |
table — Mesa
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title; translations.content como filas separadas por líneas verticales y delimitadas por barras verticales. |
| Configuraciones y variantes | settings.variant: header-row/default or plain. Legacy settings.rows remains readable but is not recommended for new API content. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico que contiene .wb-table-wrap > table.wb-table, <thead> opcional y <tbody>. |
| Aspecto de ejemplo | Pequeña tabla comparativa o de especificaciones. |
| Evitar | Cuadrículas de diseño de página o conjuntos de datos interactivos. |
quote — Cita
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Cotización de translations.content, piezas de atribución de translations.title y translations.subtitle. |
| Configuraciones y variantes | settings.variant: default or testimonial. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico con <blockquote class="wb-stack wb-gap-2">; El testimonio agrega un caparazón de tarjeta silenciado. |
| Aspecto de ejemplo | Cita editorial o testimonio de cliente. |
| Evitar | Llamadas de uso general. |
Bloques de navegación
link-list — Lista de enlaces
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle, translations.content; copia del enlace secundario. |
| Configuraciones y variantes | settings.row_layout: index (default), stacked puts each row description under its title. settings.list_frame: joined (default), cards gives each row its own card. Independent; ambos se pueden escribir a través de la API. |
| Niños/medios de comunicación | Sólo link-list-item. |
| HTML | Envoltorio genérico con pila de introducción opcional y .wb-link-list, además de wb-link-list--stacked / wb-link-list--cards para los estilos seleccionados. |
| Aspecto de ejemplo | Índice de recursos con título, metadatos, descripción, íconos e insignias. |
link-list-item — Elemento de la lista de enlaces
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Insignia translations.title requerida, subtitle, content y eyebrow opcionales; URL requerida compartida. |
| Configuraciones y variantes | icon_slug, icon_tone, icon_size, badge_tone. |
| Niños/medios de comunicación | Imagen en miniatura opcional media_id; previsto en Lista de enlaces. |
| HTML | <a class="wb-link-list-item"> with an optional leading thumbnail or icon (adding wb-link-list-item--media), title/meta/badge, and optional description. |
| Aspecto de ejemplo | Fila de documentación/recursos marcada como "Nuevo". |
| Hacer guardia | Se emite únicamente con una URL y un título seguros. |
page-list — Lista de páginas
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Sin copia de página. Los títulos, descripciones y miniaturas provienen de la traducción de cada página enumerada: name, luego list_excerpt, volviendo a seo_description, luego og_image_media_id. |
| Configuraciones y variantes | scope (page_type, path_prefix, subtree_of_current), page_type, path_prefix, sort, limit (1-48), layout (cards/links), columns, show_thumbnail, show_description, exclude_current, clickable_card. |
| Niños/medios de comunicación | Ni. Las filas provienen de una consulta de página; Las miniaturas se resuelven a partir de la imagen Open Graph de la traducción de cada página. |
| HTML | wb-grid de artículos wb-card (o raíces de tarjeta de enlace único cuando clickable_card está habilitado), o un wb-link-list de anclajes wb-link-list-item. |
| Aspecto de ejemplo | Un índice de tres columnas de tarjetas guía, cada una vinculada desde su título. |
| Hacer guardia | No emite nada cuando la consulta no devuelve páginas o mientras el alcance no está configurado. El estado de publicación, el sitio, la traducción de la configuración regional, las páginas de origen Shared Slot y la página de alojamiento se filtran en la consulta y no son configuraciones. |
application — Bloque de aplicaciones
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Sin copia editorial. Selecciona una aplicación integrada registrada en la base de datos mediante application_handle estable. |
| Configuraciones y variantes | application_settings se valida con el esquema de definición seleccionado. Las configuraciones de presentación propiedad del CMS son width, loading, aspect_ratio, min_height, show_loading_state y show_failure_state. |
| Niños/medios de comunicación | Ni. Los activos ejecutables pertenecen a la definición de la aplicación registrada y no se pueden suministrar a través de contenido de bloque o medios. |
| HTML | Las aplicaciones en línea reciben un .wb-application__mount generado; Las aplicaciones iframe reciben un iframe en espacio aislado propiedad de CMS. CSS y JavaScript declarados mediante definiciones listas se cargan una vez por página. |
| Creación de API | Se puede escribir a través de validación/aplicación de contenido y parche de configuración de bloqueo directo. Descubra identificadores con GET /webadmin/api/applications y esquemas con /applications/{application}/schema; estas lecturas requieren applications.read. La mutación del registro no está expuesta. |
| Hacer guardia | Las definiciones faltantes, no válidas o duplicadas no cargan recursos ni se ejecutan. No representan nada a menos que el estado de falla genérico traducido del bloque esté habilitado. |
navigation-auto — Navegación automática
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Sin copia de página; menú de navegación CMS seleccionado. |
| Configuraciones y variantes | menu_key desde ubicaciones de menú conocidas. Las claves de pie de página/legales muestran enlaces apilados; primario/predeterminado representa enlaces de estilo botón agrupados. |
| Niños/medios de comunicación | Registros de navegación, no bloquear a los niños. |
| HTML | Envoltorio genérico más árbol semántico <nav> y <ul>. |
| Aspecto de ejemplo | Menú de navegación de compatibilidad en una ranura. |
| Recomendación | Prefiera la navegación en la barra de navegación para los nuevos encabezados compartidos. |
| Brecha en el registro de contratos | Este identificador publicado tiene un formulario de administrador y un procesador, pero no tiene ninguna entrada en BlockTypeContractRegistry en la línea base de auditoría. No infiera un contrato API activo completo hasta que el descubrimiento lo confirme. |
toc — TOC Vídeo
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Título compartido opcional. |
| Configuraciones y variantes | Ninguno. |
| Niños/medios de comunicación | Lee bloques de encabezado publicados en la misma ranura con anclajes válidos y variantes H2/H3, en el orden del documento. |
| HTML | Envoltorio genérico con una lista de enlaces nav.wb-section-nav generada: una primitiva WebBlocks UI autónoma, no wb-link-list. |
| Comportamiento en vivo | El resaltado de la posición de desplazamiento viene de forma gratuita desde el módulo WBSectionNav enviado en el mismo webblocks-ui.js que ya carga el diseño público; el renderizador no posee ningún JavaScript propio. |
| Aspecto de ejemplo | Lista de “Contenido” para una página de documentación larga. |
| Hacer guardia | No emite nada cuando no existen títulos elegibles. |
breadcrumb — Migaja de pan
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Compartido home_label; El título de la página actual proviene de la página. |
| Configuraciones y variantes | include_current: boolean. |
| Niños/medios de comunicación | Utiliza el contexto de página/sitio/localización. |
| HTML | Envoltorio genérico más <nav class="wb-breadcrumb"><ol class="wb-breadcrumb-list">…</ol></nav>. |
| Aspecto de ejemplo | Inicio / Categoría / Página actual. |
header-actions — Acciones de encabezado
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Sin copia. |
| Configuraciones y variantes | Booleanos show_search, show_mode_toggle, show_accent_toggle, show_language_switcher. Los controles públicos preestablecidos/de acento actualmente están suprimidos por el modelo de tema público a nivel de sitio. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más controles compactos de iconos .wb-topbar-actions. |
| Aspecto de ejemplo | Búsqueda y acciones en modo claro/oscuro/automático en el lado derecho de la barra de navegación. |
| Evitar | CTA comerciales. |
sticky-navbar — Barra de navegación
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Sin copia directa; layout_name opcional solo para editor. |
| Configuraciones y variantes | sticky_mode: sticky/default, static, fixed. |
| Niños/medios de comunicación | Hijos permitidos: contenedor, clúster, encabezado, plain_text, texto enriquecido, button_link, marca de barra de navegación, navegación de barra de navegación, acciones de encabezado, formulario de búsqueda. Al menos un niño requerido por los planes API. |
| HTML | Propiedad de raíz <nav class="wb-navbar …" data-wb-public-block-type="sticky-navbar">…</nav>. |
| Aspecto de ejemplo | Encabezado compartido: Barra de navegación → Contenedor → Clúster (entre) → Marca + navegación/acciones. |
| Evitar | Un segundo shell de encabezado personalizado. |
navbar-brand — Marca de la barra de navegación
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle; URL compartida, destino, etiqueta aria. |
| Configuraciones y variantes | url; target: _self or _blank; aria_label. |
| Niños/medios de comunicación | Imagen opcional media_id para logotipo. |
| HTML | Wrapper genérico plus <a class="wb-navbar-brand"> con imagen y copia de identidad opcionales. |
| Aspecto de ejemplo | Logotipo, nombre del sitio y eslogan conciso. |
navbar-navigation — Navegación en la barra de navegación
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Título compartido como etiqueta ARIA; menú de navegación seleccionado. |
| Configuraciones y variantes | menu_key; active_indicator: underline, pill, dot, background, none; active_matching: path, section, current-page, exact, off. |
| Niños/medios de comunicación | Árbol de elementos de navegación de CMS. |
| HTML | Contenedor genérico más enlaces .wb-navbar-links de escritorio, menú desplegable WebBlocks UI móvil, clases activas y menús desplegables de grupos. |
| Aspecto de ejemplo | Navegación primaria responsiva con menú de hamburguesas automático. |
sidebar-brand — Marca de la barra lateral
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, translations.subtitle; URL compartida, destino, etiqueta aria. |
| Configuraciones y variantes | Mismo contrato de enlace seguro que Navbar Brand. |
| Niños/medios de comunicación | Imagen opcional media_id para logotipo. |
| HTML | Envoltorio genérico plus <a class="wb-sidebar-brand"> con logo y copia identificativa. |
| Aspecto de ejemplo | Logotipo/título de la documentación en la parte superior de una barra lateral. |
sidebar-navigation — Navegación de la barra lateral
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title como etiqueta ARIA; Editor opcional layout_name solo. |
| Configuraciones y variantes | Opcional menu_key; show_icons: boolean; active_matching: path, current-page, exact. |
| Niños/medios de comunicación | Ya sea registros de navegación CMS o manual sidebar-nav-item / sidebar-nav-group; Se requiere al menos un niño en los planes API manuales. |
| HTML | Envoltorio genérico más estructuras de barra lateral <nav class="wb-sidebar-nav"> y WebBlocks UI. |
| Aspecto de ejemplo | Barra lateral de documentación con indicación de sección activa. |
sidebar-nav-item — Elemento de navegación de la barra lateral
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Requerido translations.title; URL y destino compartidos. |
| Configuraciones y variantes | icono del catálogo; active_mode: exact, path, current-page, manual; manual_active: boolean. |
| Niños/medios de comunicación | Ninguno; previsto en Navegación de barra lateral o Grupo de navegación de barra lateral. |
| HTML | <a class="wb-sidebar-link"> or nested .wb-nav-group-item, with optional icon and active state. |
| Aspecto de ejemplo | Enlace de documentación manual. |
sidebar-nav-group — Grupo de navegación de barra lateral
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Requerido translations.title; Editor opcional layout_name solo. |
| Configuraciones y variantes | icon; initially_open: boolean. |
| Niños/medios de comunicación | Sólo sidebar-nav-item. |
| HTML | .wb-nav-group with button toggle, arrow, icon, and .wb-nav-group-items. |
| Aspecto de ejemplo | Grupo plegable de “Guías” en una barra lateral de documentos. |
search-form — Formulario de búsqueda
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Etiqueta translations.title, marcador de posición translations.content, etiqueta de envío translations.subtitle. |
| Configuraciones y variantes | settings.variant: primary or secondary; show_button: boolean. |
| Niños/medios de comunicación | Ninguno; Requiere una ruta de búsqueda de sitio que se pueda resolver. |
| HTML | Contenedor genérico más <form role="search" class="wb-cluster …">, entrada nativa y botón WebBlocks opcional. |
| Aspecto de ejemplo | Campo de búsqueda del sitio en un encabezado o página. |
sidebar-footer — Pie de página de la barra lateral
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | Nota de pie de página translations.title, translations.content, translations.subtitle. |
| Configuraciones y variantes | settings.variant: info, success, warning, danger. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más .wb-sidebar-footer, .wb-callout tonificado y nota silenciada opcional. |
| Aspecto de ejemplo | Pequeño aviso de documentación o nota de versión. |
Bloques de patrón, forma y compromiso
alert — Alerta
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | translations.title, se requiere translations.content. |
| Configuraciones y variantes | settings.variant: info, success, warning, danger. |
| Niños/medios de comunicación | Ninguno. |
| HTML | Envoltorio genérico más <div class="wb-alert wb-alert-{tone}"> y título opcional. |
| Aspecto de ejemplo | Advertencia en línea, nota de éxito o mensaje informativo. |
| Evitar | Promociones de marketing. |
contact_form — Formulario de contacto
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | title, content, submit_label, success_message, consent_label de propiedad local. |
| Configuraciones y variantes | recipient_email; send_email_notification; store_submissions sigue siendo propiedad del producto en el contrato nativo; consent_required (booleano, falso por defecto). |
| Consentimiento | Establezca consent_required y asigne a la configuración regional un consent_label para representar una casilla de verificación de consentimiento requerida. La redacción se traduce porque es el aviso. Un envío aceptado almacena consent_accepted_at más una copia del texto, por lo que editar el bloque más tarde no puede cambiar lo que se registra que un visitante anterior aceptó. Un consentimiento requerido sin texto para la configuración regional resuelta no muestra ninguna casilla de verificación en lugar de una sin etiqueta. consent_required está cerrado a PATCH: eliminar un aviso legal de un formulario en vivo es una decisión del operador. |
| Política de notificación del sitio | Los formularios de contacto y los complementos participantes comparten Site.notification_settings, se leen mediante GET /webadmin/api/sites/{site}/notifications (content.read) y se modifican mediante PATCH (site-settings.write, con alcance del sitio). Campos: notification_mode (full, alert_only), notification_frequency (immediate, batched, daily), batch_minutes (1–60), daily_summary (booleano), summary_hour (0–23 en la zona horaria del sitio). Los campos PATCH omitidos se conservan; Se rechazan los valores no válidos, nulos y desconocidos. Estas son configuraciones del sitio, nunca bloquee los campos PATCH. |
| Privacidad de notificaciones | alert_only solo tiene copias de sitios confiables, recuentos y enlaces de bandeja de entrada de CMS autenticados normales. Sin nombre/dirección del visitante, asunto/cuerpo, IP, información del navegador, URL de origen/referencia, respuesta del visitante, encabezados personalizados ni archivos adjuntos. Los mailables mínimos separados nunca reciben modelos de visitantes. full conserva notificaciones detalladas, incluidos lotes detallados. Los resúmenes diarios siempre contienen recuentos y enlaces protegidos, incluso cuando el modo de contenido seleccionado es full. Los complementos no pueden anular el modo de privacidad del sitio. |
| Temporización de notificación | Los sitios nuevos tienen por defecto alert_only, batched, diez minutos, un resumen de daily habilitado a las 09:00. Las migraciones de actualización conservan el comportamiento completo/inmediato existente con los resúmenes deshabilitados. El correo de contacto por lotes envía la primera alerta inmediatamente y luego combina los mensajes posteriores por sitio/canal/destinatario. El chat en vivo se agrupa por conversación para que cada conversación reciba su primera alerta fuera de línea de inmediato. daily envía un resumen combinado por sitio/destinatario/día; con daily_summary habilitado, se recuerda el trabajo pendiente existente daily. Los mensajes de contacto leídos permanecen en espera de respuesta hasta que se respondan/archiven; Se excluyen los mensajes spam, en cuarentena, archivados y excluidos. |
| Entrega y extensión de complemento | webblocks:notifications:dispatch is registered every minute with the Laravel scheduler; los hosts deben ejecutarlo y usar un caché compartido que admita bloqueos atómicos cuando ejecutan varios trabajadores. La inscripción almacena los identificadores y el estado del sitio/canal/fuente únicamente, con claves de fuente únicas; La política se vuelve a leer antes de la entrega. Los fallos son genéricos y nunca se reintentan automáticamente. Los intentos interrumpidos fracasan después de 15 minutos. Los eventos terminales y el estado de envío inactivo se eliminan después de 30 días. GET expone los resultados de los mensajes del sitio y los resultados de los resúmenes diarios más recientes; el panel de configuración del sitio y las bandejas de entrada existentes muestran el estado de entrega. Los complementos habilitados registran un adaptador SiteNotificationChannel a través de SiteNotificationChannels con su identificador de complemento, que posee fuentes de alcance del sitio, destinatarios, elegibilidad, correo detallado y recuentos pendientes; Los complementos deshabilitados no se envían. |
| Notificaciones del panel | Desde CMS 1.96.0, la cabecera compartida de administración enlaza al panel de notificaciones del Dashboard mediante la acción WebBlocks UI wb-btn wb-btn-ghost wb-btn-icon y el contador wb-btn-badge. Las cifras visibles se limitan a 99+; la etiqueta accesible conserva el número exacto. Los responsables de operaciones ven los totales de mensajes no leídos (new) y pendientes de respuesta (new + read) de los sitios accesibles, más una advertencia de programación si alguno necesita correo programado y su estado registrado no está verificado, está retrasado, ha fallado o no está disponible. Desde CMS 1.97.0, la insignia de cabecera cuenta solo mensajes no leídos; los leídos pendientes de respuesta y las advertencias de programador/esquema permanecen separados en el Dashboard y no cuentan en la insignia. Sin mensajes no leídos, la campana sigue visible sin cifra. La celda Actions de la fila del sitio usa el icono estándar de visualización de WebBlocks UI con ayuda traducida y etiqueta accesible que explica que abre mensajes pendientes de respuesta. El trabajo almacenado se muestra independientemente de la suscripción al correo, destinatarios, resultado de entrega o evidencia del programador. No entran en el resumen nombres, direcciones, asuntos, contenidos ni IP de visitantes. Las lecturas no envían correo, consumen eventos, marcan mensajes como leídos ni establecen salud del programador. Los recuentos se actualizan al cargar cada página del panel; representan el estado actual compartido de la bandeja, no un historial personal ni consultas automáticas. Los enlaces usan GET /webadmin/contact-messages?site={id}; el selector de sitio se valida y se conserva en URL seguras de regreso a la bandeja. Se excluyen mensajes respondidos, archivados, spam y en cuarentena; la falta de esquema muestra una advertencia de migración en vez de una bandeja vacía. Live Chat conserva su indicador separado de panel del plugin, limitado por permisos y sitio, que también funciona sin correo programado. |
| Estado y requisitos previos del programador | CMS 1.95.1 registra en la base de datos una devolución de llamada realmente programada cada minuto, separada de inicios/finalizaciones/fallos del comando de notificaciones. El valor required derivado de la política del sitio es true para entregas agrupadas/diarias o resúmenes diarios. Desde CMS 1.95.2, el Dashboard tiene un único aviso de salud con enlaces a todos los sitios accesibles para los responsables de operaciones, incluidos los antiguos con entrega solo inmediata. La gravedad depende de si algún sitio accesible necesita notificaciones programadas; los inaccesibles no influyen. Las políticas solo inmediatas sin resumen diario conservan una tarjeta informativa que explica que la programación es opcional para esas notificaciones; los ajustes y la API GET de notificaciones del sitio muestran scheduler_health con estados general/programador/trabajador y marcas UTC. La falta de evidencia permanece unverified; la evidencia de más de 300 segundos pasa a delayed; los errores de procesamiento y el esquema no disponible son explícitos; una ejecución actual sin terminar puede estar running. El envío manual y las lecturas de salud no crean un latido del programador. El comando de solo lectura webblocks:scheduler:status --json termina correctamente solo con estado saludable verificado. La ejecución del programador no garantiza la entrega SMTP/bandeja ni la salud de cada nodo. El instalador y el aviso de configuración de invitados explican el correo operativo, APP_URL canónica, un programador del servidor cada minuto y una caché compartida con bloqueos atómicos para varios trabajadores; el CMS nunca instala cron. Los plugins de notificaciones habilitados pueden usar el mismo servicio SchedulerHealth en ajustes y comprobaciones de salud. |
| Niños/medios | Ninguno. |
| HTML | Envoltorio genérico alrededor de section.wb-card nativo, formulario protegido por CSRF, campo antispam generado por el renderizador, entradas de WebBlocks, área de texto, casilla de verificación de consentimiento opcional, errores de validación y botón de envío. |
| Ejemplo de apariencia | Formulario de contacto totalmente administrado almacenado en Mensajes de contacto con notificación opcional. |
| Evitar | Formulario sin formato HTML, campos de honeypot personalizados o reemplazo de mailto:. |
rating — Clasificación
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | El encabezado y texto de apoyo opcionales por idioma (title, subtitle) usan traducciones de texto. El antiguo settings.title sigue como alternativa de representación; el producto traduce las etiquetas normales. |
| Configuraciones y variantes | scale: fixed 5; allow_change: boolean; show_summary: boolean; data_scope (CMS 1.97.0): block (predeterminado, conserva áreas de comentarios separadas) o page (mismo sitio/página almacenado, sobrevive al reemplazo del bloque). Tanto el editor como el PATCH de bloque admiten el alcance. |
| Niños/medios | Utiliza content_ratings; sin hijos. |
| HTML | <section class="wb-card"> propietario de raíz con H3 opcional, .wb-rating-stars parcialmente lleno, resumen y botones de envío sin JS .wb-rating-input. |
| Ejemplo de apariencia | Calificación de página de cinco estrellas con promedio y recuento de respuestas. |
| Nota | Solo los votos activos de 5 puntos entran en el resumen público. El alcance de página mantiene estable el hash de sesión al reemplazar bloques, serializa escrituras bajo un bloqueo de página y reconoce hashes de bloque supervivientes de la sesión actual. Los hashes antiguos huérfanos no pueden asociarse ni deduplicarse automáticamente; las filas existentes no cambian hasta actualizar un voto reconocido. El formulario marca el voto actual con aria-pressed y desactiva entradas repetidas cuando allow_change es false; el servidor también lo aplica. GET no crea un identificador de visitante. |
comments — Comentarios
| Área de contrato | Comportamiento respaldado por fuente |
|---|---|
| Contenido editable | No hay copia para visitante con autor en bloque; traducciones de productos suministramos etiquetas y mensajes. |
| Configuraciones y variantes | form_enabled, show_approved, show_author_name; sort_order: newest or oldest; data_scope (CMS 1.97.0): block (predeterminado) o page. El alcance de página incluye registros aprobados del mismo sitio/página almacenado, incluso si se eliminó el bloque original; se excluyen páginas y sitios vecinos. |
| Niños/medios | Utiliza comment_entries moderado; sin hijos. |
| HTML | Raíz propia <section class="wb-card wb-public-comments"> con regiones Comments/lista y Leave a comment/formulario etiquetadas por separado (CMS 1.97.1), encabezados traducidos por el producto e insignia de número aprobado. Autor/fecha comparten una fila de metadatos que se ajusta; el texto multilínea escapado usa espaciado compacto. El formulario tiene una superficie tenue según el tema, un área de texto de tres filas y un campo de nombre compacto que se amplía en móviles. Conserva la paginación de 25 entradas (comments_page_{block_id}, preservando fragmento y consulta), protección CSRF nativa, campos antispam, validación específica y acción de envío. La visibilidad de lista y formulario sigue siendo independiente. |
| Ejemplo de apariencia | Comentarios moderados debajo de un artículo o guía de producto. |
| Evitar | Almacenamiento de comentarios personalizado o marcado de formulario sin formato. |
Bloque avanzado solo para humanos
html — HTML (confiable)
| Área de contrato | Comportamiento respaldado por la fuente y política de destino |
|---|---|
| Propósito | Se revisó la trampilla de escape humana para obtener un margen de beneficio confiable que aún no tiene un contrato de producto estructurado. |
| Contenido editable por el administrador | Contenido confiable de HTML. El registro de traducción actual lo trata como contenido de una familia de textos. |
| Configuraciones y variantes | Ninguno. Los fragmentos de superposición/final de cuerpo reconocidos se pueden extraer a registros de paquetes. |
| Niños/medios de comunicación | Sin niños. |
| HTML | Envoltorio genérico más un <div> interior simple que contiene marcas confiables; Los fragmentos extraídos pueden aparecer fuera de la raíz visible. |
| Creación de API | Prohibido. No se permiten creación, actualización, reemplazo, mutación de topología, mutación destructiva, mutación por etapas ni mutación de publicación. |
| Comportamiento de la IA | Informar una brecha de capacidad y proponer un bloque/variante/renderizador estructurado. Nunca genere una carga útil HTML grabable. |
Identificadores heredados y de solo renderizador
No trate un Blade parcial como prueba de que hay un identificador disponible para nuevo contenido API. La fuente actual contiene renderizadores de compatibilidad y filas borrador que no son contratos de creación principales publicados.
Las filas del borrador del catálogo incluyen:
text
card-grid
tabs
menu
faq-list
showcase-list
contact-info
Los identificadores de solo renderizador, alias, parciales o de compatibilidad incluyen ejemplos como:
accordion
faq
button
callout
list
map
metric-card
stats
testimonial
gallery-viewer
sidebar-nav-item-link
sidebar-navigation-menu-item
fallback
missing-renderer
Reglas:
- Nunca cree estos simplemente porque existe un archivo de renderizado.
- Úsalos solo si el catálogo de bloques autenticado en vivo informa el identificador exacto publicado y utilizable para la instalación actual.
- Prefiere los bloques estructurados canónicos documentados anteriormente.
- Los parciales internos, como el visor de galería y los renderizadores de enlaces de la barra lateral, nunca son tipos de bloques de plan de contenido.
Recetas de composición visual
Estos son árboles de bloques administrados, no plantillas fijas. Confirme todos los identificadores en tiempo de ejecución.
Comience desde la receta menos enmarcada que satisfaga el contenido. No repita la misma receta en bandas de páginas adyacentes y no seleccione la receta de la tarjeta de características simplemente porque la fuente contiene tres elementos breves.
Introducción editorial con medios en primer plano
section(spacing:lg)
└── container(width:xl)
└── hero(layout:split, foreground media)
├── button_link(primary)
└── button_link(secondary)
Utilice una imagen grande y significativa y un estilo de superficie sobrio. Elija layout:full-bleed cuando la imagen deba convertirse en una banda de apertura sin marco que abarque toda la ventana gráfica; conservar split cuando la imagen sea contenido semántico de primer plano.
Principios o beneficios sin marco
section(spacing:lg)
└── container(width:xl)
└── columns(variant:plain)
├── column_item
├── column_item
└── column_item
Este es el punto de partida normal para cualidades como experiencia, comunicación, atención, rapidez o confiabilidad. Promuévalo a Tarjetas solo cuando los elementos sean procesables de forma independiente o estén limitados.
Introducción a la página de marketing con acciones independientes
section(background optional)
└── container(width:lg)
├── hero(variant:accent, layout:centered)
└── cluster(alignment:center, gap:sm)
├── button_link(primary)
└── button_link(secondary)
Uuse esto solo cuando la fila de acción deba ubicarse fuera de la raíz de promoción del héroe. El propio Hero acepta elementos secundarios de Button Link en todos los diseños, incluido el dividido; mantenga las acciones dentro de Hero cuando esa sea la composición prevista.
Cuadrícula de tarjeta de entidad delimitada
section(spacing:lg)
└── container(width:lg)
├── header(h2)
└── grid(columns:3, gap:4)
├── card
│ └── card_body
│ ├── header(h3)
│ ├── plain_text
│ └── button_link
├── card
└── card
Todos los títulos, párrafos y acciones se pueden editar de forma independiente. Reserve esta receta para entidades acotadas como productos, complementos, planes, descargas o servicios con acciones propias. Utilice el sitio CSS para obtener una apariencia de tarjeta consistente y específica del sitio a través de ganchos estables; no inyectar tarjeta HTML.
Imagen alternada y filas de copia
section
└── container
├── grid(columns:2, alternate_media_text_sections:true, alternate_start:media_left)
│ ├── image
│ └── card or content stack
└── grid(columns:2, alternate_media_text_sections:true)
├── image
└── card or content stack
Use utiliza imagen para medios de primer plano. Utilice un bloque con capacidad de fondo solo cuando la imagen sea semánticamente un fondo.
Barra de navegación responsiva compartida
sticky-navbar(sticky)
└── container(width:lg)
└── cluster(alignment:between, width:full)
├── navbar-brand
└── cluster
├── navbar-navigation
└── header-actions
Las etiquetas de navegación y las URL pertenecen a registros de navegación de CMS, no a HTML.
Control deslizante de imagen administrada
slider(height:viewport, autoplay:false, show_arrows:true, show_dots:true)
├── slide(background media)
│ └── container
│ ├── header
│ ├── plain_text
│ └── button_link
└── slide(background media)
└── container
└── card
└── card_body
└── rich-text
Flujo de trabajo de diseño a CMS
Antes de aplicar un diseño visual, genere una tabla de mapeo:
| Región de diseño | Propietario del contenido | Árbol de bloques | Variante/configuración | Ganchos estables CSS | Estado de capacidad |
|---|---|---|---|---|---|
| Héroe de ejemplo | Traducciones de páginas y biblioteca multimedia | Sección → Contenedor → Héroe | acento, centrado, medios de fondo | [data-wb-public-block-type="hero"], .wb-promo | Solo se admite si la promoción de medios de fondo coincide con el diseño. |
Para cada región:
- Identifique cada copia editable, medio, acción, insignia, datos de navegación y registro dinámico.
- Asigna cada pieza a un campo nativo editable por el administrador.
- Confirmar reglas padre/secundario y renderizador HTML.
- Confirme que la composición visual es posible con el DOM documentado.
- Use el sitio CSS solo para presentaciones que el DOM estable pueda admitir.
- Si falta algún campo semántico, contenedor, ranura o variante, marque la región como no compatible.
- Proponga la capacidad de complemento o CMS reutilizable más pequeña: una variante de renderizador, un nuevo bloque estructurado, un patrón compuesto de bloques existentes o un bloque de dominio como una colección de productos de Commerce.
- No aplique un sustituto de baja fidelidad a sabiendas a menos que el usuario apruebe explícitamente ese compromiso.
Formato de informe de brecha de capacidad:
Region: Storefront hero
Required editable content: title, body, two actions, foreground product image, offer badge, trust items
Current closest block: hero
Supported: title, eyebrow, body, background image, promo tone
Missing: foreground media slot, split DOM, trust-item collection, discoverable managed action child
Why CSS is insufficient: required semantic wrappers and editable fields do not exist
Recommended product change: add a reusable split/storefront Hero variant and structured trust-item children
HTML fallback: prohibited
CSS Orientación
Utilice capas de estilo en este orden:
- Primitivas WebBlocks UI ya emitidas por el renderizador.
- Fichas de tema público y roles de color públicos que reconocen el modo.
- Configuraciones y variantes de bloques nativos.
- Estreche el CSS específico del sitio utilizando ganchos estables.
- Un renderizador reutilizable o un cambio de contrato de bloque cuando falta el DOM requerido.
Los selectores estables incluyen:
body[data-wb-public-theme] {}
[data-wb-public-block-type="hero"] {}
[data-wb-public-block-type="card"] {}
.wb-promo {}
.wb-card {}
.wb-content-header {}
No utilice el sitio CSS para:
- insertar texto esencial con pseudoelementos;
- depende de los ID de bloque generados;
- inferir semántica del orden de hermanos;
- hide contenido creado por CMS simplemente para reemplazarlo con contenido CSS;
- reconstruir un diseño faltante con posicionamiento absoluto frágil;
- codificar colores solo claros que interrumpen el modo Claro/Oscuro/Automático.
Brechas de fuentes conocidas en la línea de base de la auditoría
Estos son hallazgos de implementación, no permisos para inventar comportamientos:
- Resuelto: este inventario ahora se envía como
resources/contracts/inventory.mdyGET /webadmin/api/inventorylo entrega a las herramientas. webblocks-cms-docs/docs/block-type-contracts.mddice 42 tipos principales publicados, mientras que el catálogo actual define 51.- Varios documentos existentes todavía muestran rutas de renderizado solo previas al paquete en
packages/webblocks-cms/...; Las rutas de paquetes actuales comienzan enresources/views/.... - Resuelto: El HTML de confianza ya no admite escritura mediante API.
BlockTypeApiAuthoringPolicybloquea todas las rutas de mutación de API, incluida la normalización genérica, el PATCH de bloque existente y las operaciones de reordenamiento, eliminación de subárboles, limpieza de todo y publicación de Shared Slot. - Resuelto: Hero y CTA son contenedores simples para elementos secundarios
button_linktanto en el administrador como en la API. Los camposprimary_cta/secondary_ctasobreviven como una taquigrafía de dos botones. La fila del catálogo heredadobuttonno publicado ya no es un bloqueador de creación. - Resuelto: el editor de elementos de columna ahora expone el campo de subtítulo que la variante Columnas
statsrepresenta como valor de estadística. - El audio tiene un selector de medios de administración normal y un procesador de medios públicos, pero la lista de medios permitidos directos del plan de contenido omite el audio.
- Resuelto: la normalización de iconos tiene un propietario.
InternalContentApiOperationscontiene la lista canónicaPUBLIC_ICON_BLOCK_TYPESmás los normalizadores de slug/tono compartidos, y el plan de contenido completo los delega, por lo que los puntos finales de bloques incrementales y los planes validan los íconos de manera idéntica. - La configuración del bloque API aún no se rige por un esquema de configuración legible por máquina por bloque. Las configuraciones desconocidas pueden sobrevivir a la normalización incluso cuando ningún renderizador o campo de administración las utiliza.
- Resuelto:
navigation-autoahora tiene un contrato documentado enBlockTypeContractRegistryy se puede descubrir a través de tipos de bloques y contratos de contenido. - WebBlocks UI envía una anatomía
wb-footer-*(wb-footer-grid,wb-footer-brand,wb-footer-nav,wb-footer-link,wb-footer-list,wb-footer-item,wb-footer-copy,wb-footer-meta,wb-footer-text,wb-footer-logo) que ningún renderizador CMS emite. En su lugar, un pie de página de ranura compartida componewb-section/wb-container/wb-grid/wb-stack/wb-clustergenérico, por lo que solo se puede acceder al patrón desde diseños escritos a mano. Cosmetic desde 1.50.0 le dio a.wb-slot-footersu propia superficie; un bloque de composición de pie de página permanece deliberadamente aplazado en lugar de pendiente. - Resuelto:
GET /content-contractderiva su secciónmedia_libraryde la tabla de rutas registrada, por lo quesupported_operationsyunsupported_operationsno pueden desviarse de lo que publicaopenapi.json. La carga, la recuperación remota, la eliminación, el reemplazo y el movimiento se publican según lo admitido con la capacidad que exige cada ruta. - Resuelto: el consentimiento tiene una mitad orientada hacia el visitante. El banner de configuración del sistema muestra el patrón de consentimiento de cookies de WebBlocks UI en páginas públicas y lo conecta al punto final
POST /privacy-consent/syncexistente, ycontact_formobtuvosettings.consent_requiredmás unconsent_labeltraducido registrado en cada envío. - El repositorio tiene capturas de pantalla de administración de páginas y panel de control, pero no tiene una galería de accesorios visuales canónica por bloque/por variante. Por lo tanto, las descripciones de “Apariencia de ejemplo” en este inventario son referencias doradas derivadas de la fuente, no respaldadas por capturas de pantalla. Hasta que exista esa galería, prefiera composiciones neutrales documentadas y evite reclamar fidelidad visual únicamente a partir de la prosa.
- Resuelto para la planificación:
GET /content-contractahora publica un contrato de dirección de diseño legible por máquina que cubre carácter, densidad, tipografía, geometría, imágenes, esquinas, contraste, roles de ritmo, política de tarjetas y lagunas de composición conocidas. Deliberadamente no persiste un registro de estilo oculto; Las herramientas de inteligencia artificial indican la dirección en su plan/informe y lo implementan a través de opciones de bloques compatibles, tokens temáticos y el sitio estable CSS.
Revisión de inventario y controles de frescura
El producto posee este contrato de ejecución. El repositorio de documentación mantiene una instantánea de la versión generada con una identidad de origen distinta; las ediciones comienzan en el contrato del producto.
Desde CMS 1.94.3, composer test:inventory y composer test:docs validan resources/contracts/inventory-review.json con el contrato actual y las huellas digitales de origen del tiempo de ejecución. Los archivos de tiempo de ejecución modificados, agregados o eliminados y los cambios de versión del producto requieren una nueva revisión explícita. CI y pre-push ejecutan la misma verificación; La preparación del lanzamiento verifica el árbol de trabajo y el generador de artefactos verifica el árbol Git seleccionado.
Después de revisar los campos admitidos, enumeraciones, elementos secundarios, medios, renderizado, comportamiento del editor, permisos y ciclo de vida del complemento, actualice esta prosa y registre la revisión con composer inventory:review -- --reviewed --note="review summary". Un contrato sin cambios después de un cambio de fuente se acepta solo con una explicación explícita --no-authoring-impact="reason". Los registros de revisión nunca deben actualizarse automáticamente mediante CI o scripts de versión.
El registro mecánico captura el catálogo principal publicado, las reglas secundarias, la propiedad de la raíz del renderizador, la política de escritura de API y el soporte de medios móviles de los asistentes reales del producto. PHPUnit compara este registro con los ayudantes actuales y la verificación de fuente requiere un encabezado de inventario único para cada bloque principal publicado. Las huellas dactilares y las comparaciones mecánicas imponen la revisión y la coherencia estructural; no prueban el significado de cada oración. Las explicaciones en prosa y sin impacto siguen siendo responsabilidad del colaborador y del revisor.
El tools/inventory-snapshot.php del repositorio de documentación regenera la instantánea y su procedencia inventory-source.json. Sus comprobaciones rechazan las ediciones manuales de instantáneas y comparan la versión del producto, la huella digital de origen, la suma de verificación de revisión y el contenido del documento con la compra de un producto seleccionado. Las comprobaciones de documentación aisladas verifican la procedencia registrada sin necesidad del producto en tiempo de ejecución. La generación de instantáneas y la publicación de CMS siguen siendo operaciones independientes.
Referencias detalladas relacionadas
webblocks-cms-docs/docs/ai-page-building-guide.mdwebblocks-cms-docs/docs/internal-content-api.mdwebblocks-cms-docs/docs/api-discovery.mdwebblocks-cms-docs/docs/block-type-contracts.mdwebblocks-cms-docs/docs/public-block-render-markup.mdwebblocks-cms-docs/docs/block-ui-renderer-contract.mdwebblocks-cms-docs/docs/public-theme-and-tones.mdwebblocks-cms-docs/docs/public-assets.mdwebblocks-cms-docs/docs/media-image-variants.md
Este inventario debería ser el primer documento que lee una IA para seleccionar la capacidad de diseño de página. Las referencias detalladas siguen siendo útiles para los flujos de trabajo de endpoints, la compatibilidad histórica y las notas completas del renderizador.
Contrato de inicio y recuperación del complemento
Instalación de catálogos y ZIP, actualizaciones y activación de panel/API validan la fuente del complemento,
inicio del proveedor, comandos y rutas en un nuevo proceso PHP a través de cms:plugin-probe.
Se requiere validación incluso cuando no hay ninguna migración pendiente. Una sonda fallida o con tiempo de espera agotado
deja el paquete actual activo; Los diagnósticos de subprocesos no se exponen en las respuestas.
El tiempo de espera de inicio predeterminado es de 30 segundos (webblocks-plugins.install.boot_timeout_seconds).
Las actualizaciones exitosas conservan el paquete anterior y registran si se ejecutaron las migraciones. Las fallas en la configuración de la base de datos dejan el complemento deshabilitado y preservan sus tablas y paquetes. Las fallas de fuente/ruta en tiempo de ejecución ponen en cuarentena el complemento; una desactivación explícita anula habilitación basada en configuración. Los registros JSON del ciclo de vida utilizan reemplazo atómico.
/webadmin/plugin-recovery y su formulario de inicio de sesión se cargan sin la fuente del complemento instalado,
rutas o comandos. Controles de inicio de sesión de CMS existentes, acceso de administrador activo y autorización Super admin, y CSRF
se aplica la protección. La recuperación puede deshabilitar un complemento o restaurar el paquete retenido cuando
no se ejecutó ninguna migración, después de otra prueba de inicio. Una restauración también vuelve a publicar sus activos.
Esta es la recuperación de paquetes administrados por CMS; no aísla proveedores de host arbitrarios
o ejecutable de zona de pruebas PHP. La terminación del proceso inatrapable todavía requiere la separación
solicitud de recuperación en lugar de un controlador de errores en proceso.
Autorización de lectura de la salud del sistema
GET /webadmin/api/system/health requiere la capacidad opcional system-health.read y un token de sistema válido para toda la instalación (allowed_site_ids: null), propiedad de un operador activo con access-system. Las credenciales personales y limitadas a sitios no pueden leer la salud de la instalación. El parámetro opcional y validado site_id filtra las comprobaciones del sitio, mientras las de toda la instalación siguen visibles.
El endpoint devuelve claves y parámetros de mensajes seguros, problemas ordenados, estados de categorías (healthy, warning, critical, unknown, not_applicable), resúmenes de sitios, información del sistema y resultados recientes de operaciones. Las observaciones de sitios, copias, almacenamiento, plugins, preparación para actualizar e historial se almacenan en caché durante cinco minutos; las pruebas del planificador se leen en cada solicitud. Las comprobaciones desconocidas y opcionales se distinguen de las satisfactorias. Leer o actualizar la salud no modifica contenido, concilia registros de copias, envía correo, ejecuta limpieza o actualizaciones, obtiene metadatos de versiones ni genera pruebas del planificador. Los informadores de plugins conservan su contrato existente de informes de salud; los mensajes sin procesar y los detalles de excepciones quedan fuera de esta vista.
Las rutas operativas existentes siguen disponibles. Los destinos de Ayuda de los plugins se incorporan a Sistema y los de Mantenimiento se combinan mediante la clave estable del grupo de mantenimiento; el elemento principal de Ayuda enlaza directamente a la documentación. El estado de salud es una prueba para revisión, no una autorización para publicar contenido, restaurar una copia o actualizar un host. Las comprobaciones de búsqueda comparan los ámbitos aptos de páginas e idiomas publicados con las filas del índice; no prueban la actualidad del texto. La disponibilidad de copias no prueba la integridad de la restauración. La preparación para actualizar permanece separada del funcionamiento normal del sitio.