construcción-de-páginas-en-webflow

Construcción de páginas en Webflow

Resumen

Las herramientas de escritura de Webflow MCP reportan éxito en operaciones que silenciosamente hicieron algo diferente de lo que solicitaste. Los nombres de clases se renombran, las imágenes no se vinculan, los estilos caen en el breakpoint incorrecto. Cada escritura debe ser leída de vuelta.

Principio fundamental: una respuesta de éxito no es evidencia. El árbol de elementos sí lo es.

Para elementos CMS, entradas de blog y SEO de página, usa una habilidad de publicación centrada en CMS en su lugar. Esta habilidad es la superficie del Designer: elementos, estilos, activos, código personalizado.

La Ley de Hierro

Nunca publiques a producción sin aprobación explícita en la conversación actual.

Una publicación del sitio envía cada cambio del Designer en escena en cada página, incluyendo trabajo que no hiciste y páginas no listadas que aún son accesibles en producción. "Ya te dije que publicaras antes" no se traslada entre tareas. Pregunta de nuevo.

El staging es diferente, y es como se revisa el trabajo. Publicar en el subdominio de staging solamente (una lista de dominios personalizados vacía) es el paso normal después de una corrección, seguido de QA en staging. Publica solo en el dominio de producción principal, nunca en todos los dominios del sitio, y solo después de la aprobación.

Las nueve trampas

1. whtml_builder renombra clases que colisionan

Pide hp2-proof cuando un estilo con ese nombre existe y obtienes hp2-proof-1. Pide hp2-proof-n y obtienes hp2-proof-n-1. Colisiones encadenadas producen hp2-proof-link-1-2. Los divs contenedores frecuentemente no obtienen ninguna clase.

Nada da error. Tu CSS principal apunta a una clase que no existe, y cualquier querySelectorAll('.hp2-proof') en un script registrado coincide con cero elementos, por lo que las animaciones de desplazamiento nunca se ejecutan.

Siempre usa query_elements por estilo después de insertar, lee los styleNames reales, y escribe tus selectores de CSS y script contra esos. Los contenedores sin clase son accesibles como .parent-class > div.

2. Una clase en html solo se aplica si ya existe

Una clase referenciada en el parámetro html se vincula solo si ese estilo ya existe en el sitio O está definido en el mismo parámetro css de la llamada. De lo contrario, el elemento se inserta sin clase y aún reporta éxito. Define cada clase que uses en css.

El builder tampoco soporta selectores descendientes. Usa clases individuales y clases combinadas (.a.b). @media y clamp() están bien.

3. whtml_builder necesita un único elemento raíz

Varios elementos hermanos en el nivel superior fallan o se insertan parcialmente. Envuélvelos en un contenedor.

4. Las imágenes insertadas como marcado no están vinculadas

Un <img> en html devuelve partial_success con "does not exist in asset library". Inserta el elemento, luego vincúlalo con set_image_asset y el id del activo.

5. update_style se enfoca por breakpoint_id, no por breakpoint

Una clave breakpoint se ignora silenciosamente y la escritura cae en el breakpoint base, sobrescribiendo el escritorio. La respuesta muestra una clave breakpoints solo cuando la escritura enfocada funcionó. Pasa breakpoint_id explícitamente y léelo de vuelta.

6. set_style reemplaza, no agrega

set_style elimina cada estilo existente y aplica solo lo que pasas. Para agregar una clase, lee primero los styleNames actuales y pasa la lista completa.

7. set_page_freeform_code reemplaza todo el bloque

El código personalizado del head y footer de la página vive en data_scripts_tool, no en las herramientas de páginas o estilo: get_page_freeform_code y set_page_freeform_code, con location: "head".

La escritura es todo o nada. No hay append. Siempre usa get para obtener el bloque actual, modifica la cadena, y set de vuelta completa. Escribir un fragmento elimina silenciosamente todo lo demás que estaba en el head. También rechaza etiquetas <script> en algunos planes, razón por la cual los scripts van en embeds (abajo).

8. Las páginas creadas a través de la API no heredan tu CSS base

Si el sitio establece su tamaño de fuente raíz en un componente CSS base (por ejemplo html{font-size:.625rem} para que 1rem sea 10px), una página creada a través de la API no recibe ese componente. Todo se renderiza 1.6 veces más grande en el Designer y al publicar. El primer elemento en cada página nueva es el componente CSS base. Verifícalo antes de estilizar cualquier cosa.

9. Las salidas de creación de activos desaparecen y los enlaces tienen límite de tasa

La salida de create_asset por debajo de cierto tamaño no se persiste, por lo que un lote de 22 activos se imprime en línea y debe transcribirse inmediatamente. set_image_asset hace una lectura y una escritura cada una: aproximadamente diez enlaces por minuto antes de un 429. Vincula en lotes de diez con un minuto de por medio, y mantén una tabla de filas de nombre, id de activo, fecha y firma.

Código personalizado y scripts

La API de scripts de página está bloqueada en algunas cuentas. Para ejecutar JavaScript en una página:

1. register_inline_script (máximo 2000 caracteres) o register_hosted_script
2. Referencia la URL alojada devuelta desde un <script src> dentro de un elemento HtmlEmbed en la página, editado a través de data_element_settings_tool con la clave code

Estructura la página como un embed por sección más un embed cargador que trae la biblioteca de animación y luego tus scripts. Versiona el nombre de visualización (sections.v17) en lugar de mutar un script registrado: update_registered_script falla en scripts en línea, y un nombre versionado se revierte editando una URL en el embed. Aloja el CSS de la página de la misma manera, versionado.

Previsualización de un borrador

Una página en borrador no se puede cambiar a publicada a través de la API, y la ramificación de páginas es una característica Enterprise. Por lo tanto, haz QA de un borrador contra una réplica local: el marcado de navegación y pie de página en vivo, el CSS del sitio, la regla CSS base y la biblioteca de animación desde un CDN.

En una pestaña oculta o panel sin cabeza, el ticker de animación se pausa. Fuerza:

gsap.ticker.lagSmoothing(0); gsap.ticker.tick();

Las capturas de pantalla de un panel oculto pintan en blanco debajo del pliegue. Traduce el cuerpo para traer una sección a la vista para una captura de pantalla, y llama a ScrollTrigger.update() después de un scrollTo real.

Activos

Tres pasos, y el tercero es el que la gente se salta:

1. create_asset con el nombre del archivo y el MD5 de los bytes sin procesar (32 hexadecimales en minúsculas)
2. POST de los bytes a la uploadUrl devuelta como multipart/form-data, añadiendo cada campo de uploadDetails más el archivo bajo file. Espera 201.
3. create_asset de nuevo con el mismo nombre y hash para finalizar.

La URL del CDN es https://cdn.prod.website-files.com/<siteId>/<assetId>_<filename>. Consulta asset-upload.md para una receta curl funcional.

Los videos se suben a través del mismo formulario (video/mp4, video/webm) y se referencian desde un embed con autoplay muted loop playsinline y un póster. El video de la página de inicio es donde se va el ancho de banda, así que sirve loops pequeños y archivos ligeros para teléfonos.

Límites de tasa

Las lecturas (query_elements, get_all_elements, get_settings) hidratan los endpoints de activos y colecciones y comienzan a devolver 429 después de un trabajo pesado con activos. Las escrituras siguen funcionando. Cuando query_elements devuelve 429, get_all_elements a profundidad 2 generalmente aún tiene éxito.

Lecturas por lotes: una llamada query_elements puede tomar múltiples consultas.

Lista de verificación de verificación

Ejecuta esto después de cada sesión de construcción y reporta los resultados, no tus intenciones.

• query_elements por nombre de estilo para cada clase que introdujiste; los nombres reales coinciden con lo que tus CSS y scripts apuntan
• Cada imagen insertada tiene un assetId en su configuración
• Los estilos de breakpoint se leen de vuelta en el breakpoint que querías
• El bloque head/footer aún contiene todo lo que tenía antes de tu edición
• La URL del script registrado en el embed coincide con la versión que acabas de registrar
• Las URLs del CDN de activos devuelven 200 con el tipo de contenido y tamaño esperados
• El componente CSS base es el primer elemento en la página
• La página en escena coincide con lo que construiste: obtén el HTML de staging y verifica, no asumas

Banderas rojas

• "La herramienta devolvió éxito, así que la clase está aplicada"
• "Escribiré el CSS ahora y verificaré los nombres de clase después"
• "Es un cambio pequeño, escribiré el bloque head directamente"
• "El usuario aprobó la publicación antes en este proyecto"
• "Publicaré en todos los dominios para que sea consistente"

Todo esto significa: lee el árbol de vuelta antes de continuar.