REQ-UX-05 · Estilos de precarga con Skeleton Screen
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 overlayloading-container(CSS global).
Pero el código no lo seguía:
| Patrón | Estado 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 |
Skeleton | 14 usos en solo 5 ficheros, dibujados a mano |
| Componentes nuevos | 7 (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.
| Componente | Forma que anticipa |
|---|---|
EsqueletoTabla | filas × columnas, con cabecera |
EsqueletoTarjetas | listas y rejillas de tarjetas |
EsqueletoEstadisticas | filas de indicadores (KPIs) |
EsqueletoPanel | composición: KPIs y tabla |
EsqueletoDetalle | pares etiqueta/valor (fichas) |
EsqueletoGrafico | área de gráfico |
EsqueletoTexto | lí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ón | Patró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 usuario | BotonCarga |
| Overlay de página completa (navegar, restaurar sesión) | CargandoPantalla |
| Diálogo o sección sin estructura fija | Cargando |
- 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 vanaria-hidden. Un lector de pantalla anuncia la espera aunque los bloques no digan nada por sí mismos, y no la anuncia dos veces.EsqueletoTextoes la excepción: está pensado para componerse dentro de otro esqueleto. motion-reduce:animate-nonerespetaprefers-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ón | Resultado |
|---|---|
npx tsc --noEmit | 0 errores |
| Suite de la web | 263/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.tsx | 17/17 (forma, anuncio accesible, movimiento y las variantes de LoadingState) |
| Suites existentes de las pantallas tocadas | 9 suites / 38 pruebas en verde (consumo, auditoría, intercambio, jobs, políticas, proyección, rate limiting, webhooks, trabajos) |
| Wiki | npm 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
ccf-almacen-web/design.md— el criterio completo en «Estados y feedback».- REQ-UX-05: Estilos de precarga con Skeleton Screen.
- design.md de patrones visuales — sección nueva.
🚧 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.
