Revisar la fidelidad visual de lo que genera la IA
Cómo comprobar que el código de un agente se ve como el diseño: lista de revisión, comparación de capturas y regresión visual con Playwright, Chromatic o Percy.
¿Qué significa “se ve igual” en una revisión?
“Se ve igual” es demasiado vago para revisar. Un agente puede acertar en la estructura general y fallar en los detalles finos, así que la revisión debe ser por lista y no por impresión general. Esta tabla sirve como punto de partida:
| Qué comparar | Qué mirar | Cómo comprobarlo |
|---|---|---|
| Tipografía | Familia, tamaño, peso e interlineado de cada nivel | Inspecciona el elemento en el navegador y compara con los valores del diseño |
| Espaciado | Márgenes y paddings entre elementos | Mide con las herramientas del navegador y compara con la escala del sistema |
| Color | Fondos, texto y bordes | Verifica que use las variables o tokens del diseño y no valores aproximados |
| Estados | Normal, hover, foco, deshabilitado, error, vacío y cargando | Fuerza cada estado y compáralo con su versión en el diseño |
| Responsive | Ancho móvil, tablet y escritorio | Redimensiona y compara con los frames de cada tamaño |
| Contenido | Textos largos, imágenes, iconos | Prueba con contenido más largo y más corto que el del diseño |
Para las medidas exactas, abre el archivo en Figma Dev Mode. Si el agente usó el servidor MCP, repasa de Figma a código con MCP para saber qué datos recibió.
¿Cómo se hace una revisión paso a paso?
- Define la referencia. El diseño aprobado, los tokens y, si existe, la captura del frame. Sin referencia no hay revisión, solo opinión.
- Captura el resultado en las mismas condiciones. Mismo ancho, mismos datos y el mismo estado que en el diseño.
- Compara lado a lado o superpuesto. Primero mira la estructura y luego los detalles de la tabla anterior. Anota cada diferencia con su captura.
- Revisa los estados, no solo la pantalla ideal. El agente suele implementar bien el estado normal y olvidar el de error o el vacío.
- Clasifica y devuelve. Distingue lo que es un error de lo que es una decisión de ingeniería y pide al agente que corrija lo primero. El proceso completo de revisión está en design QA.
- Fija lo aprobado. Cuando el componente esté bien, conviértelo en una prueba automática.
¿Por qué le importa a un diseñador?
Porque la fidelidad visual es el punto donde tu trabajo se convierte en producto. Un error de espaciado de cuatro píxeles en un botón no rompe nada, pero se acumula con otros veinte y el resultado ya no parece tu diseño. Además, cada cambio que hace el agente puede romper algo que ya estaba bien: un refactor del componente de tarjeta puede mover el texto de una pantalla que nadie revisó.
Tú eres quien sabe qué es “correcto”. El agente no tiene esa referencia salvo que se la des en forma de diseño, tokens o capturas. Para ver los cambios antes de aplicarlos, mira previsualizar cambios.
¿Cómo lo automatizas?
Cuando un componente ya está aprobado, puedes fijar su aspecto con una prueba de regresión visual. Playwright la implementa con toHaveScreenshot:
- En la primera ejecución no hay referencia: Playwright avisa de que la captura no existe y la escribe. Revísala y confírmala en el repo.
- En las ejecuciones siguientes, compara la captura nueva con la guardada.
- Si el cambio es intencional, actualizas la referencia con
npx playwright test --update-snapshots.
Las opciones principales son threshold, que fija la diferencia de color permitida por píxel (de 0, estricto, a 1, laxo; por defecto 0.2), maxDiffPixels y maxDiffPixelRatio, que fijan cuántos píxeles pueden diferir, y mask, que tapa zonas con contenido variable. Playwright desactiva por defecto las animaciones durante la captura. Según su documentación, los renderizados varían entre sistemas operativos, versiones, hardware y modos, y recomienda correr las pruebas en el mismo entorno donde se generaron las referencias.
Si tu equipo ya usa Storybook, hay alternativas en la nube. Storybook explica que las pruebas visuales toman una captura de cada story y la comparan con una referencia (la última captura buena), y que comparan los píxeles que ve el usuario, no el HTML. Chromatic, hecho por el equipo de Storybook, las ejecuta en un navegador en la nube y te pide confirmar si cada cambio es intencional. Percy, de BrowserStack, captura la interfaz en varios navegadores y anchos, resalta la diferencia a nivel de píxel y permite aprobar o pedir cambios, y puede bloquear el merge en GitHub si no se aprueba.
Un flujo útil con agentes: el agente implementa el componente, corre la prueba y, si falla, te muestra la diferencia. Tú decides si es un error o un cambio aprobado.
¿Cuándo NO conviene la prueba visual?
- Cuando el componente cambia cada semana. Actualizar referencias todo el tiempo convierte la prueba en ruido.
- Cuando el contenido es dinámico: fechas, avatares o datos en tiempo real. Sin datos fijos, la prueba falla sin motivo, salvo que los tapes con
mask. - Cuando todavía no hay diseño aprobado. Una referencia de un borrador fija un error.
Ejemplo
Ejemplo ilustrativo: un equipo aprueba el componente Tarjeta de producto en tres estados: normal, con oferta y agotado. Escribe una prueba visual para cada uno con datos fijos. Un día un agente cambia el padding de la tarjeta para “mejorar el espacio” en una tarea de otra pantalla. La prueba falla con una diferencia en el borde derecho. El diseñador revisa el diff, ve que el cambio no estaba en el diseño y pide al agente que lo revierta.
Sin la prueba, ese cambio habría pasado a producción sin que nadie lo notara.
Errores comunes
- Confiar en la impresión general y no en la lista de puntos.
- Actualizar las referencias sin revisar la diferencia. Es como aceptar cambios sin leerlos.
- Usar datos reales o aleatorios en las pruebas visuales.
- Generar referencias en tu laptop y correr las pruebas en el CI. Los renderizados no coinciden.
- Revisar solo el estado normal y olvidar error, vacío y cargando.
- Pedirle a una IA que diga si “se parece” y tomar esa respuesta como prueba. Usa la IA para señalar, y tus ojos y las pruebas para decidir.