webflow-build

Compilación de Webflow: diseño aprobado → Webflow, sección por sección

La persona aprueba cada decisión de diseño; Claude construye, verifica e informa. Una sección está terminada solo cuando coincide con el diseño aprobado en todos los anchos, funciona después de cualquier forma de llegar a ella y sus pasos manuales están listados.

• checklists.md controla cada paso: la entrega del diseño, la base de Webflow, la página de medios, cada componente, cada página terminada y la entrega de la compilación. El progreso se registra en docs/handoff/progress.json con pnpm progress (checklists.md › Cómo registrar el progreso), que el panel de Tareas de Bench muestra.
• conventions.md establece la estructura de página y sección, la nomenclatura de clases y variables, y los patrones de componente, CMS y guía de estilo desde los que comienza cada compilación.
• lessons/ contiene lo que consumió tiempo en compilaciones anteriores, por área. Lee el archivo del área en la que estás a punto de trabajar.
• El prototipo siempre va primero: se construye a partir del archivo de Figma, página por página, en Bench (o por Claude en la terminal con los mismos pasos), y el cliente lo aprueba antes de construir cualquier cosa en Webflow. Los pasos están a continuación (El prototipo, desde Figma); la habilidad webflow-prototype tiene la configuración del proyecto, las entradas, la instantánea y la guía de estilo, y su figma.md explica cómo leer el archivo.
• rules.md tiene las reglas que comparten todas las habilidades de Webflow (no hacer commit ni push sin un OK, Designer primero, sin credenciales en el chat, pasos manuales, lecciones), el cierre de sesión y cómo contribuir.
• starter-site.md describe el sitio Webflow de inicio que un proyecto duplica, con el sistema base ya incluido.
• La habilidad webflow-style-guide crea la página de guía de estilo, la primera página del prototipo y de la compilación de Webflow, en el único diseño que usa cada sitio.
• media.md es la página de medios: donde se suben los videos de un sitio para que Webflow los convierta y aloje, construida antes de la primera página que reproduzca uno.
• Un sitio que ya está en vivo no es una compilación: usa la habilidad webflow-audit (auditar, luego lotes pequeños verificados; también para correcciones puntuales).
• Después de la entrega de la compilación, la habilidad webflow-launch toma el control: QA previo al lanzamiento, día de lanzamiento, entrega al cliente y los primeros 30 días.

Cada elemento de la lista de verificación indica quién lo hace:

• [Claude] Claude lo hace (a través del MCP, el repositorio o un script).
• [Claude checks] Claude lo verifica e informa; una persona arregla lo que Claude no puede.
• [Person] una persona lo hace (cliente, PM, diseñador, DNS, cuentas). Claude puede recordarlo y rastrearlo, nunca reclamarlo.

Inicio de sesión (cada sesión)

1. Lee el CLAUDE.md del espacio de trabajo, luego AGENTS.md y GOTCHAS.md de este repositorio, luego docs/handoff/ (HANDOFF.md, MANUAL-TODO.md, BUILD-NOTES.md y REVIEW.md una vez que la fase de revisión haya comenzado). Ojea lessons/README.md y lee el archivo de lecciones para el área de hoy (trabajo con MCP: lessons/mcp.md). Nunca repitas un error ya registrado.
2. Lee la memoria del proyecto: dónde se detuvo la última sesión, pasos manuales abiertos, preguntas abiertas. Ejecuta pnpm progress show para la etapa, las listas de verificación aún abiertas y las tareas pendientes de la persona. Di en una línea dónde están las cosas y qué sigue; pregunta qué página o sección si no está claro.
3. Ejecuta Antes de construir en checklists.md antes del primer lote de Webflow; la etapa Prototipo antes de que esté terminada (las entradas son las de webflow-prototype). Acuerda cualquier cambio en conventions.md con el diseñador. Si falta una entrada, pídela; no adivines contenido, estados o campos SEO.
4. Webflow MCP: llama a webflow_guide_tool una vez, luego reutiliza un mismo id de sesión e id de agente para toda la sesión.
5. El servidor de desarrollo del prototipo está en ejecución y webflow-build.config.json existe (pnpm new-project lo escribe; webflow-prototype › Configuración del proyecto).
6. El alcance de hoy es una página (ver Ritmo de trabajo). Di cuál.

Reglas permanentes

Las reglas compartidas están en rules.md. La compilación añade:

• Pregunta antes de crear, editar o eliminar clases y variables, un lote a la vez, con nombres y valores. Una solicitud que claramente las implique (por ejemplo, 'complétalo en Webflow' después de aprobar un mock) es el OK.
• Publicar depende de si el sitio está en vivo.
  • Compilación nueva (sin dominio personalizado adjunto): publicar en el dominio de staging webflow.io está bien.
  • Sitio en vivo: una publicación afecta a todo el sitio. Envía todo lo pendiente, incluyendo ediciones inconclusas de otras personas. Publica solo en staging, verifica qué más se publicaría y espera a que la persona escriba 'publicar' antes de hacerlo en el dominio personalizado (webflow-audit tiene los pasos).
  • Nunca publiques en un dominio personalizado, cortes un release o cambies DNS sin preguntar.
• Después de cada lote de escritura en Webflow, di dos cosas: 'recarga el Designer' (una pestaña abierta del Designer no muestra los cambios del MCP, y guardar desde una pestaña obsoleta puede sobrescribirlos), y qué no se ha publicado aún.
• Marca los pasos manuales en la página. Una fila de MANUAL-TODO.md que deje algo visiblemente incompleto (un valor aún faltante, un enlace no realizado) recibe un marcador junto al elemento, o junto a su espécimen en la guía de estilo: un Título con data-manual-todo="<letra>" y el texto 'Paso manual : <qué>'. Aparece en el lienzo y en staging, para que nadie revise el estado incompleto como si fuera el diseño. Elimínalo en el lote que marque la fila como completada; no debe quedar ninguno en la entrega de la compilación ni en el lanzamiento (busca data-manual-todo en el HTML publicado).

El prototipo, desde Figma

Cada sitio comienza desde un archivo de Figma. El prototipo se construye a partir de él, página por página, y se aprueba antes de construir cualquier cosa en Webflow.

En Bench. Añadir cliente › desde un diseño de Figma configura la carpeta del cliente, el repositorio desde esta plantilla y un prototype/ vacío (una copia de prototype-starter/). Construir el prototipo desde Figma agrupa los frames en páginas; la persona los selecciona y ordena, cada uno con su dirección. Un trabajo de IA luego los construye una página a la vez: cada página llega como su propio mensaje con los ids de nodo de sus frames. Cada página construida mantiene su frame de Figma para Comparar › Con Figma. Bench vuelve a mirar el archivo cuando el cliente lo abre y cada hora, y ofrece actualizar las páginas cuyos frames cambiaron: cambia solo lo que cambió en esos frames, y conserva las ediciones hechas en el prototipo desde entonces.

No en Bench, Claude sigue los mismos pasos en la terminal: lista los frames, acuerda las páginas, su orden y direcciones con la persona, luego construye una página a la vez.

Una página:

1. Sus frames. Los frames con el mismo nombre en Escritorio, Tablet y Móvil son una página. Lee cada uno con el conector de Figma (get_design_context, get_screenshot, get_variable_defs) o el servidor MCP de la aplicación Figma (figma.md). Sin frame de Tablet: dibuja Tablet entre Escritorio y Móvil. Sin frame de Móvil: haz que funcione en un teléfono desde los frames más grandes, y dímelo. Los frames que no son páginas (la guía de estilo) se leen para tokens, tipo y componentes.
2. Tokens de las variables y estilos de texto del archivo, como propiedades personalizadas de CSS: cambios en las variables de la instantánea y otras nuevas en src/css/proposed.css (antiguo → nuevo), nombrados por conventions.md §4; nunca en el tokens.css generado.
3. Fuentes que usan los estilos de texto, en public/fonts/ con su licencia, declaradas en src/css/prototype.css y precargadas en partials/head.html.
4. Imágenes exportadas del archivo a prototype/images/: fotos como WebP en el tamaño más grande que usa el diseño, iconos como SVG.
5. Solo lo que está en el archivo. Un valor, estado, texto o imagen que el archivo no proporcione es una pregunta: pregunta antes de inventarlo (en Bench, agrégalo con mcp__bench__todo_add y continúa).
6. Dónde va: prototype/<página>/index.html en su dirección de Webflow (Inicio es prototype/index.html), añadido a pages en prototype/vite.config.js. La navegación y el pie de página son parciales compartidos. Cambia solo esa página, más los parciales y tokens que necesita. No hagas commit, push ni publiques.
7. Verifícala junto a sus frames en Escritorio, Tablet y Móvil, y que los enlaces del prototipo de Figma funcionen (menús, pestañas, formularios).

Luego la página ejecuta Página prototipo terminada (checklists.md de webflow-prototype) y la persona la aprueba (en Bench: clic derecho en Páginas). La etapa Prototipo en checklists.md lo rastrea todo, hasta la aprobación del cliente por escrito:

• cada página coincide con su frame de Figma en Escritorio, Tablet y Móvil (verificación 'Coincide con el frame de Figma' de Bench);
• el archivo de Figma está vinculado al cliente;
• frames seleccionados, en orden, cada uno con su dirección de página;
• cada frame seleccionado construido como página prototipo;
• tokens, fuentes e imágenes provienen del archivo; nada inventado;
• los enlaces del prototipo de Figma funcionan;
• cada página aprobada en el prototipo;
• el cliente aprobó el prototipo por escrito.

El orden de una compilación

Comienza una vez que la etapa Prototipo está terminada. La estructura y los nombres siguen conventions.md. Cada paso está controlado en checklists.md:

1. variables;
2. estilos de etiqueta (configurados una vez en el Designer para que el MCP pueda acceder a ellos);
3. clases;
4. colecciones CMS;
5. el puerto del repositorio (módulos y CSS del repositorio desde el prototipo) y el cargador, para que staging ejecute el código real → Base terminada;
6. la página de guía de estilo, la primera página construida (habilidad webflow-style-guide) → Base de guía de estilo terminada;
7. la página de medios, cuando cualquier página reproduzca un video (media.md) → Medios terminados;
8. componentes, construidos desde el marcado de página real (nunca desde vistas previas de la guía de estilo), cada uno añadiendo su fila de guía de estilo → Componente terminado;
9. páginas, sección por sección → Página terminada;
10. la verificación final de la guía de estilo, luego Entrega de la compilación;
11. la fase de revisión: docs/handoff/REVIEW.md enumera lo que está construido por página, cada ronda de comentarios y lo que queda antes del lanzamiento, hasta que la habilidad webflow-launch toma el control.

Un sitio duplicado desde el iniciador ya tiene la base de los pasos 1 a 3 y el shell de la página; el proyecto añade a ello. Antes de cada importación, ejecuta pnpm wf:preflight; planifica los lotes de clases con pnpm wf:styles (ver Verificaciones).

El bucle de sección

Para cada sección, en orden de página:

1. Lee el prototipo: su marcado, CSS y el módulo que lo anima, con el frame de Figma de la página para estados y la especificación de interacción. Anota cada hook data-*, id y atributo aria.
2. Verifica qué tiene Webflow: clases (query_styles), componentes y sus props, campos CMS, activos. Reutiliza antes de crear; nombra cualquier cosa nueva según conventions.md (secciones 2–4).
3. Construye, prefiriendo, en orden:
   • instancias de componentes;
   • el constructor de elementos para elementos DOM (button, ul/li cuando los roles ARIA deben sobrevivir, svg, span con etiqueta), con hijos anidados;
   • importación WHTML para marcado simple, luego arregla lo que elimine (ver la lista de verificación del importador a continuación). El contenido de la página vive en el slot G | Main del componente G | Page W. En una página cuyo slot aún está vacío: construye las secciones en un wrapper To Slot después de G | Page W, pide a la persona que arrastre el wrapper al slot, luego desagrupa (mueve cada hijo antes del wrapper, elimina el wrapper). Una vez que una sección está en el slot, construye directamente al lado (conventions.md §1). Verifica el contenido del slot con query_elements; el árbol de página muestra los slots como vacíos.
4. Conecta atributos, enlaces CMS, valores de props, enlaces, configuraciones de formularios.
5. Publica, luego ejecuta las verificaciones. Arregla, vuelve a publicar, vuelve a verificar.
6. Informa: qué se construyó, qué coincidió, qué difiere y por qué, pasos manuales y los archivos que esperan un OK para commit.

Cuando una página esté completa, ejecuta Página terminada en checklists.md.

Lista de verificación del importador (después de cada importación WHTML)

• <button> se convirtió en un Enlace → reconstruir como DOM button, mover los hijos.
• <img> perdió todos sus atributos y su enlace de activo → set_image_asset, re-añadir data-*, loading, tamaño (o una clase con aspect-ratio).
• <span> se convirtió en un Span de texto → formas como <div>; piezas de texto divididas como DOM span (de lo contrario, editar el texto del padre las aplana).
• Una lista de clases con una clase faltante perdió todas sus clases → crear clases primero, re-verificar styleNames.
• Los elementos DOM mantienen un atributo class literal → remove_attribute class.
• Un espacio normal antes de <br> se elimina → Line.&nbsp;<br>Next.
• Los atributos booleanos necesitan un valor (muted="true") o la publicación los elimina.
• Las listas se publican como role="list" → mantener roles ARIA en DOM ul/li.

Higiene del lienzo

• Cada clase en un elemento vacío: padding 0 en todos los lados y font-size: inherit (el .wf-empty del lienzo añade 75px de padding y font-size 0).
• Cada cuadrícula establece al menos una plantilla de fila y una de columna; centra los hijos únicos con flex, no con cuadrícula.
• Un elemento dibujado solo por un pseudo-elemento (un glifo de fuente de icono) recibe un espacio como su texto (set_settings, clave text), para que no esté vacío.