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:

  1. ¿Qué contenido permanece editable en el administrador del CMS?
  2. ¿Qué configuraciones y variantes compartidas son compatibles?
  3. ¿Qué relaciones secundarias y de medios son válidas?
  4. ¿Qué público estable HTML emite el renderizador?
  5. ¿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 Tarjeta variant. Este documento anteriormente indicó que no existía ningún campo de variante visual de tarjeta compatible, lo cual era incorrecto desde 1.40.5 en adelante.
  • link-list (1.40.10): settings.row_layout y settings.list_frame.
  • link-list-item (1.40.8): miniatura opcional de media_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.php
  • src/Support/BlockTypes/BlockTypeContractRegistry.php
  • src/Support/Blocks/BlockTranslationRegistry.php
  • src/Models/Block.php
  • src/Http/Requests/Admin/BlockRequest.php
  • src/Support/InternalContentApi/InternalContentPlanService.php
  • src/Support/InternalContentApi/InternalContentApiOperations.php
  • src/Http/Controllers/InternalContentApi/InternalContentResourceController.php
  • src/Http/Controllers/InternalContentApi/InternalSharedSlotController.php
  • src/Http/Controllers/InternalContentApi/InternalApiDiscoveryController.php
  • routes/admin.php
  • resources/views/admin/blocks/types/*.blade.php
  • resources/views/admin/blocks/settings/*.blade.php
  • resources/views/pages/partials/blocks/*.blade.php
  • public/cms/css/public.css
  • Pruebas de paquetes enfocadas y documentación actual del producto

Reglas de creación de IA no negociables

  1. 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.
  2. html es 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.
  3. 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.
  4. Use solo campos, valores de enumeración, roles de medios y relaciones secundarias documentados aquí y confirmados mediante descubrimiento en vivo.
  5. 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.
  6. 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.
  7. 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.
  8. 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 nativas wb-*, clases de cuerpo de página y configuraciones documentadas.
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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 translations para 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_header y link-list-item también acepta una referencia opcional de nivel superior mobile_media_id un registro de la biblioteca multimedia de imágenes. Se almacena en block_media con rol mobile_image, compartido entre configuraciones regionales y editable a través de los medios de administración selector y PATCH /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íe null para 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_items o gallery_media_ids.
  • Uuse solo children anidado; no envíe id, parent_id, block_id, slot_type_id o block_type_id.
  • La API actualmente acepta un objeto settings de 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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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.
Á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:

  1. Identifique cada copia editable, medio, acción, insignia, datos de navegación y registro dinámico.
  2. Asigna cada pieza a un campo nativo editable por el administrador.
  3. Confirmar reglas padre/secundario y renderizador HTML.
  4. Confirme que la composición visual es posible con el DOM documentado.
  5. Use el sitio CSS solo para presentaciones que el DOM estable pueda admitir.
  6. Si falta algún campo semántico, contenedor, ranura o variante, marque la región como no compatible.
  7. 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.
  8. 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:

  1. Primitivas WebBlocks UI ya emitidas por el renderizador.
  2. Fichas de tema público y roles de color públicos que reconocen el modo.
  3. Configuraciones y variantes de bloques nativos.
  4. Estreche el CSS específico del sitio utilizando ganchos estables.
  5. 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:

  1. Resuelto: este inventario ahora se envía como resources/contracts/inventory.md y GET /webadmin/api/inventory lo entrega a las herramientas.
  2. webblocks-cms-docs/docs/block-type-contracts.md dice 42 tipos principales publicados, mientras que el catálogo actual define 51.
  3. Varios documentos existentes todavía muestran rutas de renderizado solo previas al paquete en packages/webblocks-cms/...; Las rutas de paquetes actuales comienzan en resources/views/....
  4. Resuelto: El HTML de confianza ya no admite escritura mediante API. BlockTypeApiAuthoringPolicy bloquea 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.
  5. Resuelto: Hero y CTA son contenedores simples para elementos secundarios button_link tanto en el administrador como en la API. Los campos primary_cta / secondary_cta sobreviven como una taquigrafía de dos botones. La fila del catálogo heredado button no publicado ya no es un bloqueador de creación.
  6. Resuelto: el editor de elementos de columna ahora expone el campo de subtítulo que la variante Columnas stats representa como valor de estadística.
  7. 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.
  8. Resuelto: la normalización de iconos tiene un propietario. InternalContentApiOperations contiene la lista canónica PUBLIC_ICON_BLOCK_TYPES má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.
  9. 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.
  10. Resuelto: navigation-auto ahora tiene un contrato documentado en BlockTypeContractRegistry y se puede descubrir a través de tipos de bloques y contratos de contenido.
  11. 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 compone wb-section/wb-container/wb-grid/wb-stack/wb-cluster gené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-footer su propia superficie; un bloque de composición de pie de página permanece deliberadamente aplazado en lugar de pendiente.
  12. Resuelto: GET /content-contract deriva su sección media_library de la tabla de rutas registrada, por lo que supported_operations y unsupported_operations no pueden desviarse de lo que publica openapi.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.
  13. 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/sync existente, y contact_form obtuvo settings.consent_required más un consent_label traducido registrado en cada envío.
  14. 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.
  15. Resuelto para la planificación: GET /content-contract ahora 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.

  • webblocks-cms-docs/docs/ai-page-building-guide.md
  • webblocks-cms-docs/docs/internal-content-api.md
  • webblocks-cms-docs/docs/api-discovery.md
  • webblocks-cms-docs/docs/block-type-contracts.md
  • webblocks-cms-docs/docs/public-block-render-markup.md
  • webblocks-cms-docs/docs/block-ui-renderer-contract.md
  • webblocks-cms-docs/docs/public-theme-and-tones.md
  • webblocks-cms-docs/docs/public-assets.md
  • webblocks-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.