Saltar al contenido principal

REQ-UX-05 · Estilos de precarga con Skeleton Screen

· 5 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

El requerimiento pide tres cosas: que se muestren esqueletos mientras llegan los datos, que aparezcan antes del contenido final y que los estilos sean consistentes en toda la aplicación.

Lo llamativo es que la primera ya estaba escrita. design.md —el sistema visual de obligado cumplimiento— decía desde REQ-DSG-01:

Carga: skeleton (esqueletos) y overlay loading-container (CSS global).

Pero el código no lo seguía:

PatrónEstado antes
LoadingState (listas y tablas)17 usos en 12 ficheros — y pintaba un spinner
Textos sueltos «Cargando…»19 sitios, cada uno con su tamaño y su color
Skeleton14 usos en solo 5 ficheros, dibujados a mano
Componentes nuevos7 (el juego completo por forma de dato)

Así que REQ-UX-05 es, en buena parte, alinear la aplicación con su propio sistema visual, y dejar por escrito lo que faltaba: cuándo corresponde esqueleto y cuándo indicador.

🧱 El juego de esqueletos​

Vive en ccf-almacen-web/src/components/carga/esqueletos.tsx, junto al patrón de carga estándar (Cargando, BotonCarga, CargandoPantalla), que es el módulo que el propio proyecto señala para el código nuevo. Se construye sobre la primitiva skeleton del catálogo, sin colores sueltos.

ComponenteForma que anticipa
EsqueletoTablafilas × columnas, con cabecera
EsqueletoTarjetaslistas y rejillas de tarjetas
EsqueletoEstadisticasfilas de indicadores (KPIs)
EsqueletoPanelcomposición: KPIs y tabla
EsqueletoDetallepares etiqueta/valor (fichas)
EsqueletoGraficoárea de gráfico
EsqueletoTextolíneas de texto

EsqueletoPanel nació de un hallazgo de la migración: varios tableros (jobs, sesiones, rate limiting, análisis de consumo) sustituyen con un solo estado de carga su fila de KPIs y su tabla. Anticipar solo una de las dos formas deja que la otra aparezca de golpe y la página crece al cargar, que es justo lo que un esqueleto debe evitar. Va bajo una sola región viva para no anunciar la espera dos veces.

Y el punto de entrada de listas y tablas gana una prop, sin cambiar el comportamiento actual:

<LoadingState label="Cargando productos…" /> // indicador, como siempre
<LoadingState variante="tabla" label="Cargando productos…" /> // esqueleto de tabla

spinner sigue siendo el valor por defecto: ningún consumidor cambia si no lo pide.

📐 El criterio (lo que hace verificable la consistencia)​

SituaciónPatrón
La espera ocupa una región cuya forma ya se conoce (tabla, lista, tarjetas, KPIs, ficha, gráfico)Esqueleto
Dentro de un botón o una acción del usuarioBotonCarga
Overlay de página completa (navegar, restaurar sesión)CargandoPantalla
Diálogo o sección sin estructura fijaCargando
  • Nunca un esqueleto para una acción del usuario.
  • Nunca un indicador centrado para una tabla o una lista de datos.

♿ Accesibilidad y movimiento​

  • Cada superficie monta una región viva (role="status" + aria-live="polite" + aria-busy) con la etiqueta como nombre accesible; las piezas van aria-hidden. Un lector de pantalla anuncia la espera aunque los bloques no digan nada por sí mismos, y no la anuncia dos veces. EsqueletoTexto es la excepción: está pensado para componerse dentro de otro esqueleto.
  • motion-reduce:animate-none respeta prefers-reduced-motion (se comprobó que la variante existe en el Tailwind instalado: addVariant("motion-reduce", "@media (prefers-reduced-motion: reduce)")).
  • La preferencia «Reducir movimiento» del usuario (UX-005) ya desactiva toda animación desde globals.css, así que los esqueletos la heredan sin trabajo extra.

🔄 Qué se migró​

15 de las 17 superficies de LoadingState declaran ahora su forma (7 tabla, 5 panel, 3 tarjetas). Las dos restantes se quedan deliberadamente con el indicador, porque el criterio las excluye: «Generar pronóstico» es una acción del usuario y la pantalla de cambio de contraseña obligatorio es una consulta breve sin región de datos que anticipar. No es un olvido.

De los 19 textos «Cargando…» sueltos, se convirtieron 9 (los que sustituyen una tabla o una lista: equivalencias, historial de devoluciones, ficha de producto, aprobaciones, detalles de solicitud, datos de despacho, tableros, contenido de ubicaciones, próximos a vencer). Los otros 10 se quedan con su justificación: un overlay de página completa, un valor suelto (la IP del cliente), formularios de preferencias, un indicador inline diminuto y un diálogo cuyo resto ya está pintado.

✅ Verificación​

ComprobaciónResultado
npx tsc --noEmit0 errores
Suite de la web263/274 — los 3 fallos son los previos de la migración TEC-019, sin regresiones; el aumento es exactamente el nuevo fichero de pruebas
esqueletos.test.tsx17/17 (forma, anuncio accesible, movimiento y las variantes de LoadingState)
Suites existentes de las pantallas tocadas9 suites / 38 pruebas en verde (consumo, auditoría, intercambio, jobs, políticas, proyección, rate limiting, webhooks, trabajos)
Wikinpm run build SUCCESS con el documento del requerimiento y el manual generados

No verificado visualmente: este entorno no tiene el stack levantado, así que la comprobación es de tipos, pruebas y build. El aspecto final de cada esqueleto sobre su pantalla queda pendiente de una revisión visual.

📌 Documentación​

🚧 Fuera de alcance​

Los ~34 LoadingIndicator que no son listas ni tablas (botones, acciones, diálogos), la app móvil (ccf-almacen-mb, que usa ActivityIndicator y no tiene esqueletos) y las landings.