UI Audit — Revisión de Interfaz y Experiencia de Usuario
Estándar de diseño: Minimalismo + Narración Animada + Mínimo Texto.
Principio fundamental: usa lo visual si es posible, las animaciones si se puede sustituir un mensaje, y el mínimo de palabras si es necesario.
Scripts Complementarios
scripts/scan-ui.sh [DIRECTORIO]: escaneo automatizado de solo lectura para detectar símbolos de texto, texto de botones demasiado largo, cadenas en chino hardcodeadas, cargas estáticas, clases CSS no definidas y otros problemas comunes de UI.
Paso 0: Verificación de Línea Base de UI (debe realizarse antes de cualquier revisión)
Línea Base de Navegación
□ El usuario puede volver a la página de inicio desde cualquier página
□ El usuario puede volver a la lista desde la página de detalles
□ El usuario puede acceder al flujo de creación/nuevo desde la página de lista
□ Al recargar la página, no se pierde la posición actual
Línea Base de Manejo de Estados
□ Cada carga de datos tiene un estado de carga (skeleton/spinner)
□ Cada llamada a la API tiene un estado de error (mensaje de error visible para el usuario)
□ Cada lista tiene un estado vacío (mensaje amigable + guía de acción)
□ El envío de formularios tiene un estado deshabilitado (evita envíos duplicados)
Línea Base de Autenticación
□ La página de inicio de sesión tiene enlace de "registro"
□ La página de registro tiene enlace de "inicio de sesión"
□ Después de iniciar sesión, redirige a una página significativa (no una pantalla en blanco)
□ Al cerrar sesión, se limpia el estado
□ Cuando el token expira, redirige automáticamente a la página de inicio de sesión
Si no se pasa la línea base, primero corrígela, no realices otras revisiones de UI.
Filosofía de Diseño
Minimalismo
□ Cada página tiene un solo punto focal visual
□ El espacio en blanco es parte del diseño
□ No más de 2 colores principales + 1 color de acento
□ No más de 1 tipo de fuente
□ Sin sombras, sin degradados, sin bordes redondeados mayores a 4px
□ Espaciado en múltiplos de 8px/16px/24px/32px
Narración Animada
□ Cada cambio de estado tiene animación de transición (150-300ms)
□ Los elementos de lista tienen animación escalonada (intervalo 30-50ms)
□ Los clics en botones tienen retroalimentación de presión (escala: 0.98)
□ La carga usa Skeleton, no un placeholder estático
□ Los errores usan animación de vibración o cambio de color, no ventanas emergentes
□ Los aciertos usan una breve animación de resaltado, no toast
Mínimo Texto
□ El texto del botón no supera 4 caracteres
□ Los botones de icono no tienen texto (usar tooltip)
□ No usar "Confirmar", "Cancelar" (usar "Guardar", "Descartar")
□ Los mensajes de error no superan 10 caracteres
□ Los elementos de navegación no superan 2 caracteres + icono
No Usar Símbolos de Texto
□ No usar → ← ↑ ↓ (usar iconos de flecha)
□ No usar × (usar icono de cerrar)
□ No usar + - (usar iconos de agregar/restar)
□ No usar > < (usar iconos de Chevron)
□ No usar ✓ ! (usar iconos de Check/Alerta)
□ No usar ~ (usar separador visual)
□ No usar % (usar barra de progreso o anillo)
Lista de Verificación
1. Revisión de Símbolos de Texto (Máxima Prioridad)
Ejecuta scripts/scan-ui.sh para escaneo automático, luego confirma manualmente si cada coincidencia necesita reemplazarse por un icono.
2. Revisión del Sistema de Iconos
□ Los iconos de operaciones comunes están completos: save / trash / edit / arrow-left / x (cerrar)
□ Los iconos de navegación están completos: search / plus / download / upload / external-link
□ Todos los iconos tienen el mismo estilo (lineal o sólido, elegir uno)
□ Los tamaños de icono son uniformes (16px para acciones, 24px para navegación, 32px para estados vacíos)
□ Los iconos provienen de la misma biblioteca (por ejemplo, Lucide / Heroicons / Phosphor), no mezclar
3. Revisión de Animaciones
□ Las transiciones de página tienen animación (fade/slide)
□ Los elementos de lista tienen animación escalonada
□ Los clics en botones tienen retroalimentación de presión
□ La carga usa animación de Skeleton
□ Los modales/menús desplegables tienen animación de apertura
□ Las operaciones largas tienen animación de progreso
Prohibido: spinner girando más de 2 segundos, etiquetas parpadeantes, animaciones en bucle infinito, animaciones complejas que afecten el rendimiento.
4. Integridad de i18n
□ Todo el texto visible para el usuario usa la función t()
□ No hay cadenas en chino hardcodeadas (excepto en archivos de traducción)
□ Los mensajes de error usan clave de i18n
□ aria-label usa i18n
5. Consistencia CSS
□ Las clases CSS referenciadas en JSX están definidas
□ No hay clases CSS no utilizadas
□ Los niveles de z-index son consistentes (modal: 200, drawer: 100, backdrop: 99, toast: 300)
□ Los colores usan variables CSS o colores de tema, sin hex hardcodeado
□ No hay !important (a menos que haya una razón clara)
6. Revisión de Código Muerto
□ Todos los archivos de componentes son importados por al menos otro archivo
□ No hay archivos con el mismo nombre (componentes duplicados en diferentes directorios)
□ No hay imports no utilizados
7. Manejo de Estados
□ Cada carga de datos tiene estado de carga
□ Cada llamada a la API tiene estado de error
□ Cada lista tiene estado vacío
□ El envío de formularios tiene estado deshabilitado
□ Las operaciones largas tienen soporte para cancelar/detener
8. Flujo de Navegación
□ Todas las rutas tienen un componente de página correspondiente
□ Las rutas protegidas tienen auth guard
□ El 404 tiene una página de respaldo amigable
□ Migas de pan/botón de volver navegan correctamente
□ Los enlaces externos se abren en una nueva pestaña
9. Capacidad de Respuesta y Accesibilidad
□ Los diseños móviles no se desbordan
□ Todos los elementos interactivos tienen aria-label
□ Operable con teclado (navegación por Tab, Escape para cerrar, Enter para confirmar)
□ Los modales/paneles tienen focus trap
□ El contraste de color cumple con WCAG AA
Flujo de Trabajo
Fase 1: Escaneo Automatizado
Ejecuta scripts/scan-ui.sh, recopila resultados. Enfoque en: símbolos de texto, texto de botones demasiado largo, falta de animaciones, chino hardcodeado, clases CSS no definidas.
Fase 2: Verificación Manual
Verifica página por página según la filosofía de diseño y la lista de verificación. Toma capturas de pantalla con Playwright de cada página para verificación.
Fase 3: Corrección
Corregir por prioridad:
- Reemplazar símbolos de texto por iconos
- Simplificar texto
- Completar animaciones
- Completar clases CSS
- Completar i18n
- Eliminar código muerto
- Manejo de estados
- Flujo de navegación
Fase 4: Validación de Regresión
Después de las correcciones, vuelve a ejecutar el escaneo automatizado para confirmar que no hay nuevos problemas.
Relación con polish-loop-v2
- polish-loop-v2: Revisión general de código (lógica, seguridad, rendimiento, tiempo de ejecución)
- ui-audit: Enfocado en UI frontend y experiencia de usuario
Ejecución paralela, línea base de verificación compartida. Los problemas de ui-audit tienen prioridad sobre los de polish-loop-v2.