Paidax01/web-to-design-md

Sitio Web a DESIGN.md

Resumen

Usa esta habilidad para convertir un sitio web real en un documento design.md o DESIGN.md reutilizable, junto con una vista previa HTML complementaria.

El objetivo no es clonar el sitio. El objetivo es inspeccionarlo lo suficientemente a fondo para que otro agente pueda recrear el mismo lenguaje de diseño, tono de contenido y sensación de interacción sin necesidad de ver el sitio web original.

La vista previa HTML es una superficie de revisión práctica. Debe traducir el markdown en un tablero de diseño visualizable para que el usuario pueda inspeccionar la paleta, tipografía, espaciado, sugerencias de componentes y el código fuente markdown sin volver a abrir el sitio.

Regla Universal del Navegador

Esta habilidad siempre debe usar agent-browser primero.

• Usa agent-browser open, agent-browser wait y especialmente agent-browser eval como el flujo de trabajo de extracción principal.
• No empieces verificando en qué aplicación o plataforma está el usuario.
• No bifurques la lógica según si el usuario está usando Codex, Trae, Claude, Cursor u otro anfitrión.
• No empieces verificando si la carpeta del proyecto actual contiene Playwright, Chrome CLI o un paquete de navegador local.
• Si agent-browser no está disponible, ayuda al usuario a instalarlo o exponerlo en PATH, luego continúa con el mismo flujo de trabajo.
• No cambies silenciosamente a Playwright, Chrome CLI o extracción basada en capturas de pantalla a menos que el usuario solicite explícitamente una alternativa separada.

Estilo de Trabajo

Trabaja primero con el navegador y primero con la evidencia.

• Prefiere agent-browser sobre las obtenciones de HTML sin procesar. Un sitio web en vivo a menudo oculta comportamientos importantes detrás de la hidratación, el estado de desplazamiento, el estado hover o los cambios de diseño responsivo.
• Trata agent-browser eval como la capa de extracción principal. La evidencia principal debe provenir de la estructura del DOM, HTML renderizado, estilos computados, variables CSS, reglas de hojas de estilo legibles y estados de interacción recopilados dentro del runtime del navegador.
• No uses capturas de pantalla como fuente de evidencia predeterminada. Cuando agent-browser eval o una ruta equivalente de evaluación de página esté disponible, usa DOM, estilos computados, variables CSS, reglas de hojas de estilo legibles y texto extraído como la evidencia principal.
• Solo usa capturas de pantalla como una verificación cruzada opcional de último recurso cuando la evidencia del DOM sea insuficiente o el usuario solicite explícitamente una verificación visual.
• No recurras silenciosamente a Playwright o Chrome CLI. Si agent-browser no está disponible, detecta eso explícitamente y ayuda al usuario a instalarlo o exponerlo.
• Trata los archivos fuente estáticos como evidencia de apoyo, no como la fuente principal de verdad.
• Traduce los detalles técnicos al lenguaje de diseño. No vuelques CSS a ciegas; sintetízalo en algo que un agente pueda usar realmente.
• Distingue los hechos observados de las inferencias. Si algo es un juicio o una regla probable en lugar de un valor directamente observado, etiquétalo claramente.
• Trata la vista previa HTML como parte del entregable predeterminado, no como un extra opcional, a menos que el usuario opte explícitamente por no incluirla.

Verificación Previa

1. Normaliza el destino en una o más URLs.
2. Verifica si agent-browser ya está disponible.
3. Si agent-browser falta, usa scripts/check-browser-tooling.mjs y luego ayuda al usuario a instalar o exponer agent-browser.
4. No inspecciones la carpeta actual en busca de Playwright, Chrome CLI o ejecutables de navegador local como ruta principal.
5. No recurras silenciosamente a Playwright o Chrome CLI a menos que el usuario solicite explícitamente esa alternativa.
6. Establece el archivo de salida markdown predeterminado como DESIGN.md.
7. Establece el archivo de vista previa complementario predeterminado como el mismo nombre base más -preview.html, por ejemplo DESIGN-preview.html o design-preview.html.
8. Si el usuario solicita explícitamente design.md, un nombre de archivo personalizado o una carpeta personalizada, respeta eso exactamente y mantén la vista previa HTML junto a él a menos que el usuario solicite lo contrario.
9. Si se proporcionan múltiples URLs, inspecciona cada una de forma independiente, luego sintetiza un sistema de diseño compartido solo cuando el lenguaje visual sea claramente consistente entre las páginas.

Inicialización de Herramientas del Navegador

Trata la configuración de las herramientas del navegador como parte de la habilidad, no como una tarea separada del usuario.

Detección

Verifica en este orden:

• si agent-browser ya se puede invocar
• si no, si se puede instalar o exponer inmediatamente

El script de verificación incluido informa:

• si node y npm están disponibles
• si agent-browser se puede invocar
• qué herramienta se debe usar a continuación
• si se recomienda la instalación

Instalación Predeterminada

Si agent-browser no está disponible, ayuda al usuario a instalarlo o exponerlo en PATH, y verifícalo con agent-browser --help antes de usar la habilidad.

Comportamiento de Instalación

• Explica que la instalación es necesaria para que la habilidad pueda usar agent-browser de manera consistente.
• Si el primer intento de instalación falla debido a restricciones de red o sandbox, solicita la aprobación necesaria y vuelve a intentarlo.
• Si la instalación tiene éxito, continúa directamente con el análisis del sitio en el mismo turno.
• Si la instalación falla, dile claramente al usuario qué falta y detente, en lugar de cambiar silenciosamente a un extractor diferente.
• No degrades silenciosamente a raspado HTML estático solo porque las herramientas no están disponibles.

Pasos de Extracción Requeridos

Usa la lista de verificación en references/website-reading-checklist.md cuando necesites un recordatorio más detallado de qué inspeccionar.

1. Delimitar la Página

• Identifica el propósito de la página.
• Identifica si la página es de marketing, producto, tablero, documentación, comercio electrónico, editorial o mixta.
• Identifica las secciones visibles importantes de arriba a abajo.
• Nota cualquier área bloqueada o inaccesible en lugar de inventarlas.

2. Capturar la Línea Base

• Inspecciona la página en escritorio primero.
• También inspecciona en tableta y móvil cuando el diseño cambie materialmente.
• Desplázate por toda la página lentamente antes de escribir algo para no perderte animaciones retrasadas, UI pegajosa o revelación progresiva.
• Captura evidencia de código del lado del navegador mientras la página está en vivo: HTML renderizado, outerHTML de nodos clave, variables CSS raíz, reglas de hojas de estilo legibles y estilos computados para componentes representativos.
• Prefiere llamadas directas a agent-browser eval o un script envolvente impulsado por agent-browser en lugar de cambiar a otra pila de navegador.
• Usa scripts/extract-browser-evidence.mjs solo cuando el usuario quiera explícitamente un artifacto JSON generado por shell mientras aún permanece en agent-browser.
• No hagas una pausa para capturar capturas de pantalla durante el paso predeterminado. Usa la evaluación de la página para extraer la estructura y los estilos directamente de la página en ejecución.

2.1 Flujo de Trabajo de Evaluación Preferido

Cuando agent-browser eval o una ruta equivalente de evaluación de navegador esté disponible, sigue este orden:

1. abre la página
2. espera la carga e hidratación
3. desplázate por la página para activar contenido diferido y cambios de estado pegajoso
4. extrae HTML renderizado para nodos representativos
5. extrae estilos computados para encabezados, botones, tarjetas, navegación y envoltorios de sección
6. extrae variables CSS raíz y reglas de hojas de estilo legibles
7. extrae fragmentos de texto visibles y copia de CTA
8. investiga los estados hover, activo, pegajoso o expandido a través del DOM o cambios de estilos computados

No reemplaces los pasos 4 a 8 con capturas de pantalla.

3. Extraer el Sistema de Diseño

Captura las reglas reutilizables, no solo la superficie específica de la página:

• colores y sus roles
• variantes de tema claro y oscuro cuando el sitio las soporte
• jerarquía tipográfica
• ritmo de espaciado y comportamiento de cuadrícula
• lenguaje de radio de esquina
• tratamiento de bordes
• sombras y capas de superficie
• estilo de imágenes
• estilo de iconos
• estilo de movimiento y transición
• filosofía de densidad y espacio en blanco
• convenciones de hojas de estilo y variables CSS cuando sean observables
• patrones de DOM que expliquen cómo están estructurados realmente los componentes repetidos

4. Extraer Componentes y Estados

Inspecciona los patrones repetidos principales:

• navegación
• barras de anuncios
• bloques de héroe
• botones y enlaces
• tarjetas
• insignias
• formularios y entradas
• pestañas o píldoras
• acordeones
• tablas
• pies de página

Para cada componente importante, inspecciona los estados visibles que importan:

• predeterminado
• hover
• activo o seleccionado
• enfocado si es visible
• deshabilitado si es visible
• variantes desplazadas o pegajosas
• estados abiertos o expandidos
• variantes de modo claro y modo oscuro cuando el sitio soporte cambio de tema

5. Extraer Comportamiento de Interacción

No te detengas en los visuales estáticos.

Documenta:

• qué cambia al desplazarse
• qué cambia al pasar el ratón
• qué cambia al hacer clic
• qué cambia cuando el usuario alterna entre modo claro y oscuro
• qué se anima en la vista
• si los carruseles, pestañas o barras laterales pegajosas se basan en clics, desplazamiento o tiempo
• qué tan rápido se siente el movimiento y si es sutil, nítido, cinematográfico, juguetón o contenido
• qué estados de CSS o DOM cambian durante esas interacciones cuando son observables en el navegador

6. Extraer Contenido y Voz de Marca

Captura el tono que da forma al diseño:

• estilo de titulares
• redacción de CTA
• densidad de oraciones
• encuadre del producto
• señales de confianza
• patrones de nombres de características
• si el texto es técnico, juguetón, premium, directo, académico o conversacional

Esto es importante porque un buen DESIGN.md debe guiar tanto los visuales como el estilo de presentación.

6.1 Barrido de Modo de Tema

Si el sitio soporta cambio de apariencia:

• activa la alternancia de modo claro y oscuro directamente en el navegador
• extrae evidencia de DOM y estilos computados para ambos modos
• documenta qué tokens se invierten versus qué acentos se mantienen estables
• nota si las imágenes, sombras, bordes, tarjetas y bloques de código cambian de tratamiento entre modos
• incluye ambos modos en el markdown final y la vista previa HTML

Contrato de Salida

Escribe el documento final usando la estructura en assets/DESIGN.template.md.

Después de escribir el markdown, genera una vista previa HTML complementaria usando scripts/render-design-preview.mjs cuando sea posible.

Cuando las herramientas del navegador estén disponibles, prefiere un paso de extracción de DOM y estilos antes de escribir. El orden de evidencia esperado es:

1. HTML renderizado y estructura de nodos clave
2. estilos computados y variables CSS
3. diferencias de estado de interacción
4. verificación cruzada opcional con captura de pantalla solo si el usuario lo solicita explícitamente o la evidencia del DOM es ambigua

Si la página soporta temas claro y oscuro, el contrato de salida también requiere:

1. documentación explícita de Modos de Tema en DESIGN.md
2. notas separadas de tokens para modo claro y modo oscuro cuando difieran materialmente
3. un bloque resumen visible de tema claro/oscuro en la vista previa HTML complementaria

El documento generalmente debe contener estas secciones:

1. Tema Visual y Atmósfera
2. Paleta de Colores y Roles
3. Reglas Tipográficas
4. Estilos de Componentes
5. Principios de Diseño
6. Profundidad y Elevación
7. Qué Hacer y Qué No Hacer
8. Comportamiento Responsivo
9. Guía de Indicaciones para el Agente

Agrega apéndices opcionales solo cuando agreguen valor real:

• Patrones de Interacción
• Patrones de Contenido y Mensajería
• Páginas Observadas
• Notas de Evidencia

Dentro de esas secciones, prefiere subsecciones más ricas al estilo Stitch cuando el sitio las soporte:

• Características Clave
• Primario, Interactivo, Escala Neutra, Superficie y Superposición, Sombras y Profundidad
• Familia Tipográfica, Jerarquía, Principios
• Botones, Tarjetas y Contenedores, Entradas y Formularios, Navegación, Tratamiento de Imágenes, Componentes Distintivos
• Sistema de Espaciado, Cuadrícula y Contenedor, Filosofía del Espacio en Blanco, Escala de Radio de Borde
• Puntos de Quiebre, Objetivos Táctiles, Estrategia de Colapso
• Referencia Rápida de Colores, Indicaciones de Componentes de Ejemplo, Guía de Iteración

No mantengas el documento al nivel de un resumen de alto nivel si el sitio expone suficiente evidencia para ser más preciso.

Contrato de Vista Previa HTML

Genera un archivo HTML junto al markdown por defecto.

La vista previa debe:

• usar el DESIGN.md final como su fuente de verdad en lugar de un resumen mantenido por separado
• usar una plantilla de shell de vista previa fija, no un framework HTML recién inventado en cada ejecución
• mostrar las reglas visuales más útiles a la izquierda, por ejemplo resumen, paleta, tipografía, espaciado, radio, botones, tarjetas, profundidad y notas responsivas
• mantener la fuente markdown visible en un panel dedicado para que el usuario pueda inspeccionar o copiar el documento original rápidamente
• parecer un tablero de diseño pulido en lugar de una representación markdown simple
• usar los tokens de diseño extraídos cuando sea práctico para que la vista previa misma refleje el sistema documentado

Usa assets/design-preview-shell.template.html como shell predeterminado cuando esté disponible. Trata esa plantilla como infraestructura estable y solo llena los tokens y contenido documentados en ella a menos que el usuario solicite explícitamente una nueva dirección de diseño.

Cuando el usuario proporcione una referencia visual para el diseño, síguela lo suficientemente de cerca como para que el HTML sea reconociblemente de la misma familia mientras se genera a partir de los datos markdown.

Reglas de Síntesis

Al escribir el archivo final:

• Prefiere nombres semánticos sobre etiquetas de tokens sin procesar.
• Incluye valores hexadecimales exactos cuando la precisión del color importe.
• Traduce las escalas de radio, espaciado, sombras y tipo a lenguaje simple que otro agente pueda usar inmediatamente.
• Mantén el documento opinado y utilizable; evita grandes vertederos de datos.
• Explica roles funcionales, no solo apariencia.
• Agrupa patrones recurrentes en un sistema.
• Preserva los matices. Si el sitio mezcla dos modos visuales, describe ambos y cuándo aparece cada uno.
• Prefiere detalles numéricos precisos cuando sean observables: valores hexadecimales exactos, tamaños de fuente, alturas de línea, espaciado entre letras, valores de radio, unidades de espaciado y fórmulas de sombra multicapa.
• Agrega una breve filosofía o justificación cuando un patrón sea central para la identidad del sitio, por ejemplo "sombra como borde" o "compresión como identidad".
• Incluye sugerencias de implementación específicas de componentes cuando ayuden a otro agente a construir UI coincidentes sin ver el sitio fuente.
• Incluye ejemplos listos para indicaciones en la Guía de Indicaciones para el Agente al menos para patrones de héroe, tarjeta, botón o navegación en sitios sustanciales.
• Cuando algunos valores sean inferidos en lugar de observados, mantenlos claramente etiquetados pero aún útiles.

Bueno:

• "Las acciones primarias usan un azul eléctrico frío #3B82F6..." (ejemplo truncado para traducción)