# Auditoría y normalización de estilos

Fecha de corte: 13 de septiembre de 2026.

> Revisión del 14 de septiembre: la [auditoría visual en navegador](auditoria-visual-2026-09-14.md) confirma incoherencias de componentes, jerarquía y tamaños efectivos que este inventario estático no detecta. La centralización descrita aquí no acredita la aprobación del diseño. El sistema visual queda pendiente de corrección y validación por función.

## Objetivo y criterio de aceptación

La aplicación debe comportarse como un único sistema visual, no como una colección de páginas con CSS independiente. Un lote de normalización solo se considera terminado cuando:

- reutiliza los tokens y patrones compartidos;
- no introduce marcos decorativos ni nuevas excepciones locales;
- conserva la jerarquía tipográfica y el significado de cada control;
- funciona en claro y oscuro;
- se comprueba a 390, 768, 1024 y 1440 px;
- supera `npm run audit:styles -- --strict` y las comprobaciones de Svelte correspondientes.

## Línea base medida

La medición procede de `scripts/auditar-estilos.mjs` sobre los archivos CSS, HTML y Svelte de `src`. La auditoría queda disponible mediante `npm run audit:styles`; con `--strict` falla si encuentra variables CSS sin declarar, pesos tipográficos inexistentes o valores que incumplen el contrato visual.

| Indicador                       |                         Línea base |
| ------------------------------- | ---------------------------------: |
| Archivos CSS/Svelte analizados  |                                132 |
| Archivos Svelte con estilos     |                                118 |
| Bloques `<style>` en Svelte     |                                120 |
| Declaraciones `font-size`       |                                518 |
| Tamaños tipográficos literales  |                                102 |
| Declaraciones de espaciado      |                               1430 |
| Espaciados literales relevantes |                                263 |
| Declaraciones de borde          |                                552 |
| Declaraciones `border-radius`   |                                169 |
| Radios literales                |                                 68 |
| Colores literales               |                                108 |
| Media queries                   |                                 97 |
| Breakpoints distintos           |                                 26 |
| Usos de `!important`            |                                  3 |
| Archivos de fuente              | 12 archivos / 4 binarios distintos |

La mayor deuda está en la fragmentación, no en un único selector: 26 breakpoints, reglas repetidas entre rutas y componentes, y dos vocabularios visuales parcialmente incompatibles entre la web/panel y Estudio. En la comprobación visual inicial de `/musica` se detectaron nueve tamaños computados y 24 controles por debajo de 44 px. A 390 y 768 px, los filtros ocupaban demasiado espacio vertical antes del contenido.

### Distribución por ámbito

| Ámbito        | Archivos | Tamaños | Tamaños literales | Bordes | Media queries |
| ------------- | -------: | ------: | ----------------: | -----: | ------------: |
| Sitio público |       33 |     162 |                14 |    137 |            34 |
| Componentes   |       56 |     158 |                15 |    206 |            38 |
| Panel         |       19 |     113 |                 2 |    105 |            10 |
| Estudio       |       17 |      70 |                70 |     70 |             9 |
| Global        |        7 |      15 |                 1 |     34 |             6 |

En la línea base, Estudio concentraba la mayor deuda: sus 70 tamaños, 27 radios y 161 espaciados eran literales. La migración posterior los asignó por función a la escala compartida, conservando por separado los anchos estructurales de su navegación.

## P0 corregidos

La primera pasada elimina errores reales antes de abordar el rediseño:

- 5 referencias a variables CSS inexistentes corregidas; la auditoría estricta devuelve ahora 0 variables sin declarar.
- 25 usos de pesos 450, 650 y 700 sustituidos por pesos disponibles; quedan 0 pesos numéricos no soportados.
- Pesos compartidos definidos como 400, 500 y 600.
- Tokens comunes de interacción, geometría, movimiento y elevación centralizados en `src/tokens.css` y cargados por la web y Estudio.
- Colisiones de significado retiradas: las curvas de movimiento usan `--ease-standard` y `--ease-emphasized`; el degradado dorado usa `--gradiente-oro` y ya no comparte nombre con un color plano de Estudio.
- Eliminado el marco exterior añadido a la cabecera del álbum: la portada y la información vuelven a agruparse por alineación y espacio, sin caja, borde, radio ni fondo decorativo.

El resultado actual de `npm run audit:styles -- --strict` es correcto: 0 variables no declaradas y 0 pesos no disponibles. Esto es un umbral de integridad, no el final de la normalización.

## Política de bordes

Los bordes se usan para explicar una relación funcional. No se usan para “decorar” o para compensar una jerarquía débil.

### Permitidos

- Límite de un control: botones, inputs, selects, textareas y controles segmentados.
- Estado de foco visible y accesible. Se prioriza `outline` para no alterar la geometría.
- Separador único entre filas contiguas de tablas o listas de datos.
- Delimitación necesaria para leer datos, estados o columnas cuando el espacio por sí solo no sea suficiente.

### Prohibidos por defecto

- Marcos exteriores alrededor de cabeceras de álbum, canción, artista o página.
- Marcos alrededor de heroes.
- Cajas para agrupar títulos, introducciones, explicaciones o secciones completas.
- Bordes añadidos solo porque un bloque se llama “card”.
- Doble separación: borde de contenedor más bordes de todas sus filas.
- Combinaciones de borde, radio y fondo elevado sin una función interactiva o de datos demostrable.

La agrupación de contenido se resuelve primero con alineación, proximidad, espacio, escala tipográfica y, solo cuando sea imprescindible, un cambio de superficie sin borde. Un nuevo borde requiere justificar cuál de las cuatro categorías permitidas resuelve.

## Contrato tipográfico

Solo se contemplan tres familias y cada una tiene una función inequívoca:

| Rol                | Familia                   | Uso                                                                     |
| ------------------ | ------------------------- | ----------------------------------------------------------------------- |
| Display/editorial  | Newsreader                | H1, H2 y grandes titulares con carácter editorial                       |
| Interfaz y lectura | Archivo                   | Navegación, controles, tablas, metadatos, cuerpo y cifras de valoración |
| Técnica            | Monoespaciada del sistema | Código, valores técnicos o datos donde el ancho fijo sea útil           |

Reglas:

- Una cifra o puntuación pertenece a la interfaz y usa Archivo, no Newsreader.
- Los nombres de canciones y álbumes usan Archivo dentro de tablas y listados; su jerarquía se expresa con tamaño y peso, no cambiando de familia.
- Los pesos válidos son 400, 500 y 600. No se introducen 450, 650 ni 700.
- El texto de interfaz no baja de 12 px. El texto táctil o accionable parte de 16 px salvo una excepción accesible y documentada.
- Los encabezados usan interlineado 1.1, la interfaz 1.35 y la lectura extensa 1.65.
- No se declara `font-family`, `font-size` o `font-weight` localmente si ya existe un rol compartido que expresa la misma intención.

## Escalas y tokens vigentes

### Tipografía

| Token                    |                 Valor |
| ------------------------ | --------------------: |
| `--fs-xs`                |                 12 px |
| `--fs-sm`                |                 14 px |
| `--fs-base`              |                 16 px |
| `--fs-lg`                |                 19 px |
| `--fs-xl`                |                 24 px |
| `--fs-2xl`               |                 34 px |
| `--fs-3xl`               |                 48 px |
| `--fs-4xl`               | fluido, de 52 a 96 px |
| `--font-weight-regular`  |                   400 |
| `--font-weight-medium`   |                   500 |
| `--font-weight-semibold` |                   600 |
| `--leading-heading`      |                   1.1 |
| `--leading-ui`           |                  1.35 |
| `--leading-body`         |                  1.65 |

### Espacio, controles y geometría

- Espaciado: `--sp-1` a `--sp-8` = 4, 8, 12, 16, 24, 32, 48 y 80 px.
- Alturas de control: compacta 36 px, normal 44 px y táctil 48 px.
- Iconos: 20, 24 y 28 px.
- Radios: detalle 4 px, botón 6 px, tarjeta/superficie 8 px, overlay 12 px y circular 999 px.
- Una altura compacta solo es válida en escritorio y para una acción secundaria no táctil. La altura normal de 44 px es el mínimo general.

### Movimiento y elevación

- Duraciones: 150 ms, 200 ms y 400 ms.
- Curva estándar: `--ease-standard`.
- Curva con salida marcada: `--ease-emphasized`.
- Sombras: `--shadow-popover` y `--shadow-modal`.
- Overlay y texto sobre imagen: `--c-overlay` y `--c-text-on-media`.

No se añaden tiempos, curvas, radios ni sombras literales si uno de estos tokens cubre el mismo papel.

## Fases de migración

### Fase 0 — Integridad del contrato

Estado: completada en su alcance inicial.

- Mantener en cero variables no declaradas y pesos inexistentes.
- Retirar colisiones de nombres entre web, panel y Estudio.
- Documentar y hacer cumplir la política de bordes.
- Incorporar la auditoría estricta a la verificación habitual.

### Fase 1 — Primitivas compartidas

Estado: núcleo compartido aplicado; quedan consolidaciones secundarias.

- Normalizar botones, iconos accionables, inputs, chips y estados de foco.
- Llevar todos los objetivos táctiles principales a un mínimo de 44 × 44 px.
- Unificar las barras de búsqueda/vista de Música y Blog: completado con
  `BarraExploracion`, incluida su adaptación móvil y el estado de foco.
- Unificar el armazón de modales de acceso, contacto y búsqueda: completado.
- Sustituir tamaños de texto inferiores a 12 px y transiciones `ease` aisladas.

### Fase 2 — Patrones de contenido

Estado: completada para los patrones compartidos identificados.

- Unificar tablas de álbumes y canciones sin borrar sus diferencias semánticas:
  completado con `TablaCatalogo`. En el ancho con índice lateral el relleno se
  compacta antes de ocultar columnas o partir títulos; las dos tablas conservan
  el mismo ancho y superan sus seis pruebas en escritorio, móvil, claro y oscuro.
- Unificar índices laterales, chips, entradillas y barras de filtros: completado.
  La base usa `BarraExploracion`, `EtiquetaColor`, `DisposicionConIndice`,
  `CampoBusquedaLocal` y `entradilla-pagina`; cada sección conserva únicamente
  sus diferencias de contenido, medida o separación.
- Eliminar marcos exteriores de cabeceras, heroes y agrupaciones editoriales:
  completado. La inspección computada conserva únicamente separadores,
  controles, tarjetas interactivas, obras gráficas y grupos de datos.
- Consolidar las reglas repetidas de tarjetas solo donde exista una entidad interactiva real.
- Corregir el filtro móvil de Música para que no desplace cientos de píxeles el contenido principal: completado.

### Fase 3 — Responsive y rutas críticas

Estado: completada para la escala de viewport y las rutas cubiertas por la batería responsive.

- Los 26 breakpoints iniciales se han reducido a siete: 30, 34, 42, 48, 60, 64 y 75 rem.
- La escala de viewport está documentada en `src/tokens.css`; la cabecera usa `75rem`
  para compactar el escritorio y `60rem` para cambiar al menú superpuesto.
- Las reglas equivalentes de la web, el panel y Estudio comparten ya esos mismos cortes.
- Revisar navegación principal, menú burger y popups sin saltos de layout.
- Validar Música, álbum, canción, artista, Juke-box, suscripciones, favoritos, búsqueda, carrito y páginas legales.
- Añadir estado intermedio de dos columnas donde una cuadrícula pase actualmente de tres a una de forma brusca.
- Proteger tablas y contenido legal frente a desbordamiento horizontal.
- La matriz de desbordamiento recorre 27 rutas públicas —incluidos artículo,
  perfil, cuenta, listas, favoritos, compra cancelada y 404— en los cuatro anchos.
- La comprobación táctil recorre 13 rutas con controles y exige 44 × 44 px en
  móvil; excluye únicamente trampas anti-bot, controles deshabilitados y nodos
  retirados del orden de tabulación.

### Fase 4 — Estudio y prevención de regresiones

Estado: migración de valores y prevención automática completadas; queda repetir la comprobación visual de Estudio con su base de datos disponible.

- La escala tipográfica, espacial y geométrica vive en `src/tokens.css` y la consumen la web, el panel y Estudio.
- Estudio ha pasado de 70 a 0 tamaños tipográficos literales, de 27 a 0 radios, de 161 a 0 espaciados y de 7 a 0 colores literales.
- Botones, campos, menú de cuenta y acciones de secciones de Estudio consumen
  las alturas compartidas de 36, 44 y 48 px según su función.
- El panel ha pasado a 0 tamaños, radios, espaciados y colores literales.
- La web pública y sus componentes han pasado a 0 tamaños, espacios y colores literales; los únicos `border-radius: 0` son reseteos y la auditoría ya no los confunde con valores de diseño.
- Retirar duplicación restante de rutas y componentes.
- Guardar capturas de referencia y ejecutar la matriz QA después de cada lote significativo.
- `audit:styles -- --strict` falla si reaparecen literales fuera de la paleta global,
  duraciones, curvas, sombras, `!important` o breakpoints ajenos a la escala de siete cortes.

## Matriz QA obligatoria

Esta matriz se ejecuta en claro y oscuro. Cada celda debe comprobarse visualmente, además de las pruebas automáticas. “Pendiente” significa que la combinación debe repetirse después de cada lote; no equivale a un fallo conocido.

|   Ancho | Tema   | Comprobaciones principales                                                                                   | Estado de cierre   |
| ------: | ------ | ------------------------------------------------------------------------------------------------------------ | ------------------ |
|  390 px | Claro  | Menú burger en overlay, controles ≥44 px, filtros compactos, sin scroll horizontal, contraste de superficies | Pendiente por lote |
|  390 px | Oscuro | Lo anterior más legibilidad de bordes permitidos, iconos y overlays                                          | Pendiente por lote |
|  768 px | Claro  | Transición móvil/tablet, navegación sin salto, tablas adaptadas, jerarquía y separación coherentes           | Pendiente por lote |
|  768 px | Oscuro | Lo anterior más contraste de filas, estados activos y modales                                                | Pendiente por lote |
| 1024 px | Claro  | Navegación completa si cabe, filtros y contenido equilibrados, cuadrículas sin cambio brusco                 | Pendiente por lote |
| 1024 px | Oscuro | Lo anterior más transparencia de cabecera y lectura sobre heroes                                             | Pendiente por lote |
| 1440 px | Claro  | Ancho útil controlado, cabeceras sin cajas, tablas a todo su contenedor, imágenes bien encuadradas           | Pendiente por lote |
| 1440 px | Oscuro | Lo anterior más fondos, sombras y contraste sin bordes decorativos                                           | Pendiente por lote |

En las ocho combinaciones se verifica también:

- claro/oscuro sin cambio de estructura;
- foco por teclado visible;
- zoom al 200 % sin pérdida de contenido o acción;
- ausencia de solapamientos, cortes y saltos al abrir menús o modales;
- estados hover, activo, reproducción y selección coherentes;
- ninguna caja exterior nueva fuera de la política de bordes;
- tipografía limitada a Newsreader, Archivo y monoespaciada técnica;
- cabeceras, filas y columnas alineadas con el mismo sistema de espaciado.

## Seguimiento cuantitativo

Después de cada fase se guarda el resultado de `npm run audit:styles -- --json` y se compara con esta línea base. Los objetivos son monotónicos:

- variables sin declarar: 0;
- pesos no disponibles: 0;
- `!important`: tender a 0;
- breakpoints distintos: descenso hasta el conjunto acordado;
- literales de tipografía, radio, espacio, color, movimiento y sombra: descenso sin reemplazarlos por tokens duplicados;
- bordes: descenso allí donde sean marcos decorativos, conservando controles, foco y datos.

La reducción de números no sustituye la comprobación visual: una regla compartida incorrecta puede producir más daño que varias reglas locales correctas. Por eso cada consolidación se valida primero en las rutas que comparten el patrón y después en la matriz completa.

## Punto de continuidad tras la normalización de escalas

Estado guardado al cerrar la sesión:

- la auditoría estricta pasa con 0 variables sin declarar y 0 pesos tipográficos no disponibles;
- la auditoría estricta pasa también con 0 infracciones del contrato visual;
- el fallback autónomo de 404/500 en `src/error.html` forma parte ahora de la auditoría y usa el mismo contrato de escala, peso y color;
- la cabecera del álbum no tiene marco, fondo ni radio decorativo;
- `src/tokens.css` contiene el contrato común de pesos, interlineados, controles, iconos, radios, movimiento, overlays y sombras;
- acceso, contacto y búsqueda comparten el mismo armazón de modal;
- Música usa un único componente de filtros y, en móvil/tablet, los muestra en un diálogo superpuesto que no desplaza el contenido;
- «Todos los álbumes» y «Todas las canciones» limpian estilo, idioma y etiquetas
  tanto en el aside de escritorio como en el diálogo compacto;
- Música y Blog comparten `BarraExploracion` para búsqueda, Tarjetas/Tabla y los
  controles adicionales de cada catálogo;
- Música, Blog, fichas y tarjetas comparten `EtiquetaColor`: el tono depende del
  nombre y los estados de enlace, selección y dato conservan la misma geometría;
- los filtros y la presentación de Música y Blog, junto con las pestañas de las
  canciones, viven en la URL y responden a Atrás/Adelante; las búsquedas locales,
  el orden de la tabla, el país de Géneros, la materia del Glosario, el borrador
  de Contacto y la configuración del Juke-box se restauran mediante snapshots al
  regresar a su página;
- las navegaciones consecutivas de etiquetas se serializan para que una segunda
  pulsación rápida parta del estado ya aplicado y no elimine la selección anterior;
- Taller y Géneros comparten `DisposicionConIndice` para la cuadrícula, el índice
  fijo de escritorio y su traslado bajo el contenido en móvil; cada sección
  conserva su índice semántico propio;
- Géneros, Letristas y Glosario comparten `CampoBusquedaLocal`, con una sola
  implementación para etiqueta accesible, enlace reactivo, foco y aspecto;
- once rutas públicas comparten `entradilla-pagina` como jerarquía tipográfica
  de introducción, manteniendo localmente solo sus márgenes y medidas especiales;
- los controles principales normalizados respetan el mínimo táctil de 44 px;
- la comprobación visual se realizó en claro y oscuro a 390, 768, 1024 y 1440 px sin desbordamiento horizontal ni errores de consola en las rutas revisadas;
- `check:sitio`, `check:panel` y `check:estudio` terminan correctamente;
- las 448 pruebas unitarias activas y las 28 pruebas responsive terminan correctamente;
- las 112 pruebas funcionales de Música, Blog, fichas de contenido,
  Taller, Juke-box y Contacto terminan correctamente contra el servidor de
  desarrollo, incluida la retirada independiente de filtros, la apertura del
  acceso como diálogo y la restauración mediante Atrás/Adelante de filtros,
  presentación, etiquetas, pestañas, búsquedas, ordenación y borradores; la
  protección CSRF se ha comprobado además contra el build de producción;
- la batería funcional de Estudio requiere PostgreSQL; el servidor de pruebas no
  puede consultarlo actualmente y falla antes del render, no en una regla de
  estilos ni en la interfaz.

Corte cuantitativo actual después de la normalización:

| Indicador                           | Valor actual |
| ----------------------------------- | -----------: |
| Archivos CSS/Svelte/HTML analizados |          139 |
| Declaraciones `font-size`           |          510 |
| Tamaños tipográficos literales      |            0 |
| Declaraciones de espaciado          |         1447 |
| Espaciados literales relevantes     |            0 |
| Declaraciones de borde              |          529 |
| Declaraciones `border-radius`       |          165 |
| Radios literales                    |            0 |
| Colores literales                   |           47 |
| Movimientos literales               |            0 |
| Sombras literales                   |            0 |
| Media queries                       |          100 |
| Breakpoints distintos               |            7 |
| Usos de `!important`                |            0 |

La línea base anterior se conserva como referencia histórica. Este corte es el punto de comparación para el siguiente lote.

Orden de continuación:

1. Repetir la matriz visual de Estudio cuando vuelva a estar disponible PostgreSQL.
2. Ejecutar la batería funcional completa si el siguiente lote modifica lógica,
   datos o navegación; los cambios actuales de presentación quedan cubiertos por
   las pruebas focalizadas y la matriz responsive.
3. Retirar el Panel heredado cuando Estudio cubra todas sus operaciones, en vez de
   compartir componentes y volver a introducir su modelo anterior.
4. Guardar capturas de referencia definitivas antes de cerrar la rama de estilos.

El primer lote responsive supera las 28 pruebas de `e2e/responsive.e2e.ts`, incluida
la matriz de anchos, la navegación, los objetivos táctiles, los filtros, las tablas,
el contraste y los estados de puntero.

Restricciones que deben mantenerse durante la continuación:

- no añadir cajas exteriores a cabeceras, heroes, introducciones ni agrupaciones editoriales;
- no modificar simultáneamente componentes no relacionados para resolver un ajuste local;
- no mezclar las escalas tipográficas de Newsreader y Archivo;
- no dar por válido un cambio responsive sin comprobarlo visualmente en ambos temas;
- mantener en cero las variables CSS inexistentes y los pesos no cargados.

### Corrección del alcance del Juke-box

La selección automática por filtros se ha sustituido por programación diaria con
franjas horarias y listas/canciones asignadas en orden. La programación se guarda
por cuenta, detecta solapamientos, admite el cruce de medianoche y continúa al
navegar. La interfaz reutiliza los controles y etiquetas del sistema visual.

Ver [operativa y validación de la programación](jukebox-programacion-horaria.md).
Validación realizada: 13 pruebas de dominio/reproductor y 8 pruebas de navegador,
incluida reproducción de audio real a la hora programada, más compilación,
comprobación de tipos y auditoría estricta de estilos.

### Juke-box: separación de pantallas y controles comunes (14 de septiembre)

La reproducción queda en el hero, seguido del pie global; la colección y la edición viven en configuración. Nombre y descripción se guardan por jukebox. El editor permite guardar una franja o todo el jukebox. Play conserva el oro y despliega la colección; los formularios usan navy en claro y celeste en oscuro. GrupoToggle unifica las selecciones exclusivas en una barra con activo verde, con estilos y tokens globales. El subtítulo del hero adapta el tamaño al ancho del título con espaciado natural; los controles quedan más altos y el estado de reproducción comparte su fila.