Guía de solicitud del agente de modernización de Experience prompting-guide

La migración sigue un flujo de trabajo de siete pasos:

1. El agente analiza la página de origen.
2. Identifica la estructura de la sección.
3. Realiza el análisis de creación.
4. Asigna el contenido a variantes de bloque.
5. Genera Markdown.
6. Crea una infraestructura de importación.
7. Previsualiza el resultado.

El agente analiza las páginas utilizando una jerarquía de dos niveles:

• Primero identifica los límites de la sección (cambios de fondo, desplazamientos de espaciado)
• Luego identifica las secuencias de contenido dentro de cada sección.

El análisis de creación sigue el modelo de David.

• Para cada secuencia de contenido, primero comprueba "¿Puede un autor crear esto escribiendo normalmente?"
• Se prefiere el contenido predeterminado (encabezados, párrafos, listas e imágenes en línea) sobre los bloques.

El agente intenta reutilizar bloques existentes de la biblioteca de bloques del repositorio antes de crear nuevos bloques.

• Cuando el contenido no se puede asignar a un bloque existente, crea nuevas variantes de bloque.
• Puede solicitar cambios, solicitar nuevas variantes o ajustar asignaciones de forma interactiva.

Las variantes de bloque se rastrean con metadatos.

• Al migrar varias páginas, el agente carga primero las variantes personalizadas existentes y las vuelve a utilizar cuando el estilo coincide (umbral de similitud del 70 % basado en el propósito, los colores, la tipografía, el espaciado y el diseño).

El encabezado, la navegación y el pie de página se excluyen de la migración de páginas. Estas se gestionan mediante habilidades dedicadas.

Cada migración crea una infraestructura de importación (plantillas de página, analizadores de bloques, transformadores) para futuras importaciones masivas.

• Esto incluye plantillas de página (estructura de sección), transformadores (limpieza DOM de todo el sitio) y analizadores (conversión de HTML a tabla específica del bloque).

• No deduce las plantillas desde cero.

• No se admite la combinación de plantillas en una sola ejecución.

Esta solicitud suele invocarse automáticamente como el primer paso de la migración de páginas.

El contenido oculto mediante CSS se captura en si está presente en el DOM.

Las imágenes cargadas de forma diferida y el contenido procesado del lado del cliente se gestionan desplazándose por la página en Chromium sin encabezado y dejando que se ejecuten los scripts.

Las imágenes WebP/AVIF/SVG se convierten a PNG por compatibilidad.

Se extraen los metadatos, incluidos el título, la descripción, las etiquetas de Open Graph, los datos estructurados JSON-LD y la URL canónica.

Las imágenes en DOM son fijas.

• la imagen de fondo se convierte en img.
• Los elementos de imagen están desajustados
• srcset se ha resuelto en src
• Las direcciones URL relativas se convierten en absolutas
• Los SVG en línea que se van a convertir en archivos img.

Se generan rutas de documentos saneadas (en minúsculas sin extensión .html).

Se obtienen los siguientes resultados:

• screenshot.png
• cleaned.html (sin scripts/estilos)
• metadata.json
• Carpeta images/ con copias locales

Los usuarios pueden preguntar por las dimensiones de la captura de pantalla y solicitar tamaños de dispositivo específicos (móvil, escritorio) para la extracción de contenido.

La extracción de contenido en varios puntos de interrupción aumenta el tiempo de procesamiento.

La migración del diseño tiene dos fases:

1. La fase 1 (en todo el sitio) extrae lo siguiente en styles/styles.css:

   • Paleta de colores global y colores de énfasis
   • Sistema tipográfico (fuentes, tamaños, pesos)
   • Sistema de espaciado (relleno, márgenes, espacios)
   • Fondos de sección (claro, oscuro, de color)
   • Estilos de componente base (botones, vínculos e imágenes)
   • Salidas a

2. La fase 2 migra estilos de bloque individuales y crea CSS específicos de bloque en /blocks/{name}/{name}.css.

El estilo de bloque (fase 2) requiere que el diseño de todo el sitio (fase 1) se complete primero.

• El sistema de diseño global proporciona propiedades personalizadas de CSS que bloquean la referencia a.

Tiempo estimado:

• Fase 1: 5-10 minutos
• Fase 2: 10 a 15 minutos

Las solicitudes ambiguas completan la migración de forma predeterminada (ambas fases).

La crítica de bloques compara un bloque migrado con su origen y aplica correcciones CSS de forma iterativa hasta que se logra un 85% de similitud visual o se completan tres iteraciones.

La aptitud requiere que el bloque se haya creado primero mediante la migración de páginas.

Una crítica de bloque sigue un flujo de trabajo de seis pasos:

1. Captura el bloque original de la página de origen mediante un selector XPath.
2. Inicializa la sesión de crítica.
3. Inspecciona el bloque original (capturas de pantalla, estilos, HTML).
4. Inspecciona el bloque migrado.
5. Compara elementos y genera una puntuación de similitud con correcciones CSS.
6. Aplica correcciones y vuelve a inspeccionar hasta que se alcanza el objetivo del 85 %.

Cada iteración muestra un informe crítico completo con todas las diferencias, aplica todas las correcciones CSS (priorizadas por el impacto visual), verifica en la vista previa, vuelve a inspeccionar y muestra las métricas de mejora.

Use la crítica de bloque una vez completada la migración de diseño.

Crítica de página realiza una comparación visual de página completa entre la página original y la migrada, iterando hasta alcanzar un objetivo de similitud del 85 % o hasta completar tres iteraciones.

Una crítica de página tiene un flujo de trabajo de cinco pasos:

1. Inicializa una sesión crítica.
2. Inspecciona todos los elementos de la página original.
3. Inspecciona todos los elementos de la página migrada.
4. Compara y genera una puntuación de similitud con correcciones CSS priorizadas.
5. Aplica correcciones y vuelve a inspeccionar hasta que se alcanza el objetivo del 85 %.

Una crítica de página necesita la dirección URL de la página de origen y la ruta migrada (por ejemplo, "/about") como entrada.

Utilice la crítica de página al validar la fidelidad general de la página o validar varios bloques simultáneamente.

Use la crítica de bloque para la validación centrada en componentes específicos.

Se recomienda el siguiente flujo de trabajo:

1. Migrar una página.
2. Aplique un diseño.
3. Ejecutar una crítica de bloques en bloques de claves
4. Ejecute una crítica de página de la aplicación para una validación completa.

Esta aptitud migra bloque a bloque, no páginas completas o archivos Figma completos.

Para obtener los mejores resultados:

• Seleccione el bloque específico que desea migrar en Figma y copie su vínculo (con node-id) o nombre.
• Proporcione el parámetro node-id en la dirección URL para establecer como objetivo el bloque exacto.

Al ejecutar esta aptitud, los siguientes pasos se realizan automáticamente en el entorno alojado:

1. Detección de estructuras de bloques: el agente lee el nodo Figma para comprender las capas y los componentes.
2. Extracción de estilos global: el agente extrae colores, tipografía y espaciado en styles/styles.css como propiedades personalizadas de CSS (tokens de diseño).
3. Creación de estilos específica del bloque: el agente crea propiedades personalizadas CSS adicionales específicas del bloque que se está migrando.
4. Asignación a bloques existentes: el agente identifica el bloque coincidente más cercano en la biblioteca de bloques del proyecto y crea una variante personalizada.
5. Generación de CSS: el agente escribe estilos que hacen referencia a las propiedades personalizadas de CSS extraídas, lo que garantiza la coherencia del diseño.
6. Descarga de recursos: el agente guarda imágenes e iconos de Figma en el espacio de trabajo del entorno alojado.
7. Generación de contenido de Edge Delivery Services: el agente crea el archivo Markdown siguiendo la estructura de bloques EDS
8. Validación de salida: el agente obtiene una vista previa del resultado y realiza una comparación visual con el diseño Figma original.

La aptitud lee primero los metadatos (paso 1) para comprender la estructura y, a continuación, extrae el contexto de diseño detallado (pasos 2-5).

• Este enfoque por fases evita problemas con archivos Figma grandes o complejos.

Esta aptitud adopta un enfoque centrado en los estilos.

• Todos los estilos se extraen como propiedades personalizadas de CSS (tokens de diseño) antes de escribir cualquier CSS.
• Esto garantiza que el bloque migrado sea coherente con el sistema de diseño.

La solicitud requiere la dirección URL de Figma (con fileKey y node-id opcional) o una clave de archivo de Figma directamente como entrada.

La navegación de Edge Delivery Services exige una estructura de tres secciones (aplicada por header.js):

1. Marca (sección 1): logotipo y vínculo de marca principal
2. Secciones (sección 2): menú de navegación principal con desplegables opcionales
3. Herramientas (sección 3): vínculos de utilidad (suscripción, inicio de sesión, carro de compras)

El contenido de navegación se encuentra en nav.md, en el directorio raíz.

Las secciones están separadas por marcadores (---).

Los elementos en negrita (**Text**) con listas anidadas crean listas desplegables.

Los vínculos en la navegación pueden representarse como botones debido al comportamiento de ajuste automático de Document Authoring.

• El bloque de encabezado incluye código para eliminar las clases de botón de los vínculos de navegación.

El agente sigue el desarrollo impulsado por contenido (CDD), un proceso obligatorio para todo el desarrollo de Edge Delivery Services.

• Preguntará por los modelos de contenido y probará el contenido antes de escribir el código.

La filosofía del CD es que las necesidades del autor van antes que las del desarrollador.

• Los modelos de contenido deben ser intuitivos para los autores, incluso si eso significa un código de decoración más complejo.

La creación del contenido de prueba primero proporciona:

• Capacidad de pruebas inmediatas
• Vínculos de validación PR para comprobaciones PSI
• Documentación viva para autores
• Descubrimiento de casos excepcionales que no se tienen en cuenta los enfoques de código primero

El agente buscará bloques similares en Colección de bloques y Grupo de bloques antes de implementarlos, para encontrar patrones y código reutilizable.

Omita el CDD solo para ajustes triviales solo de CSS (pero identifique el contenido de prueba para su validación).

Edge Delivery Services tiene cuatro tipos de modelos canónicos:

• Independiente: Elementos visuales/narrativos distintos (hero, blockquote)
  • Tabla única con contenido de bloque
• Colección: Contenido semiestructurado repetido (tarjetas, carrusel)
  • Tabla con patrón de fila repetida
• Configuración: contenido dinámico o controlado por API donde se muestran los controles de configuración (lista de blogs, resultados de búsqueda)
  • Tabla con filas de configuración clave-valor.
• Bloqueo automático: Estructuras complejas que los autores crean como secciones/contenido predeterminado y luego se transforman (pestañas, incrustaciones de YouTube)

Hay un límite de cuatro celdas por fila.

• Agrupe los elementos relacionados en celdas.

Para las diferencias de estilo, prefiera las variantes de bloque sobre las celdas de configuración.

Seguir la ley de Postel: Sea flexible con la estructura de entrada.

• Un bloque a pantalla completa debe funcionar tanto si el contenido está en una celda, dividido en dos celdas o en filas independientes.

Esta aptitud suele ser invocada automáticamente por el desarrollo impulsado por contenido durante la creación del bloque.

La Colección de bloques se ha mantenido y analizado en Adobe por sus prácticas recomendadas, su excelente modelado de contenido, su alto rendimiento y su accesibilidad.

• Se limita a bloques que se necesitan con frecuencia. Empiece aquí.

Block Party es impulsado por la comunidad y ofrece una variedad más amplia que incluye enfoques experimentales.

• También incluye complementos de barra de tareas, herramientas de compilación (webpack, vite, sass) e integraciones.
• Utilícelo cuando la colección de bloques no tenga lo que necesita.

Piense en nombres alternativos al buscar

• FAQ = acordeón
• Galería = carrusel/presentación
• Navegación = menú/encabezado

La Parte del bloque sólo devuelve entradas aprobadas o revisadas.

Las pruebas siguen una filosofía de "valor frente a coste" en la que se crean y mantienen pruebas cuando su valor supera el coste.

• Las pruebas de mantenimiento (pruebas unitarias) son para utilidades con gran lógica, procesamiento de datos e integraciones de API. Son regresiones rápidas, fáciles de mantener y capturadas en el código reutilizado.
• Las pruebas de rendimiento (pruebas del explorador) son para transformaciones DOM y validación visual. Utilice para validar la implementación, capturar capturas de pantalla para la revisión de PR y luego descartar.

Las pruebas de desecho entran en test/tmp/ y prueban contenido en drafts/tmp/ (ambas ignoradas).

Antes de abrir una PR, asegúrese de lo siguiente:

• Las pruebas existentes se superan
• Las pruebas unitarias se escriben para la nueva lógica
• La validación del explorador ha finalizado
• Se prueban todas las variantes
• Se ha verificado el comportamiento interactivo
• Pasadas de entintado

Los problemas comunes tienen patrones conocidos:

• Imágenes que muestran "about:error": generalmente falta la llamada createOptimizedPicture en el bloque JS, o se llama antes de la reestructuración del DOM
• Bloques que no se representan: Compruebe el formato del nombre del bloque en Markdown y compruebe que el bloque tiene .js y .css archivos en blocks/.
• CSS no se carga: compruebe las rutas de archivo, compruebe que el archivo CSS existe y compruebe la ficha Red en el explorador.
• Los cambios no aparecen: La sincronización de código tarda de 3 a 5 segundos. Actualice (Ctrl+Mayús+R).

El agente comprueba cada capa de forma sistemática:

1. Archivos Source
2. Salida procesada
3. Código de bloque
4. Consola del explorador

El agente puede comprobar las vistas previas locales en http://localhost:3000.