ADR-0007 · Clave za-theme unificada en localStorage

ADR-0007 · Clave za-theme unificada en localStorage

  • Status: ✅ Accepted
  • Fecha: 2026-03-10
  • Tags: ui · theming

Contexto

Cada módulo del sistema (venta, caja, cashflow, articulos, listas) era desarrollado por separado y cada uno usaba su propia clave de localStorage para persistir el modo dark/light:

  • venta-theme
  • caja-theme
  • theme-mode
  • darkmode

Problema: el usuario activaba dark en venta, navegaba a caja, y veía light de nuevo. Pésima UX.

Decisión

Una sola clave compartida para todo el sistema:

const KEY = 'za-theme';
const value = localStorage.getItem(KEY) || 'dark';   // default: dark
document.documentElement.setAttribute('data-theme', value);

Implementación · patrón anti-flash

Para evitar el "flash of unstyled content", todos los HTML del sistema tienen este script como primera línea del <head>:

<head>
<script>
(function(){
  var t = localStorage.getItem('za-theme') || 'dark';
  document.documentElement.setAttribute('data-theme', t);
})();
</script>
<!-- ... -->
</head>

El CSS usa variables sobre [data-theme='dark']:

:root {                       /* light por default */
  --bg-page:    hsla(217,33%,97%,1);
  --text-main:  hsla(220,40%,12%,1);
}
[data-theme='dark'] {
  --bg-page:    #0b1120;
  --text-main:  #f8fafc;
}

Consecuencias

✅ Tema persistente en todo el sistema — incluye venta, caja, cashflow, articulos, listas, landing /reportes/, análisis HTML, y ahora también docs.zonasaridas.com.ar (Grav). ✅ Sin flash — el atributo se setea antes de que el CSS pinte. ✅ Default dark — coherente con el branding del sistema.

Aplicación

Todos los HTML del sistema siguen este patrón:

Módulo Archivos con anti-flash
/reportes/index.php ✅
/reportes/venta/*.php ✅
/reportes/caja/*.php ✅
/reportes/cashflow/*.php ✅
/reportes/articulos/*.php ✅
/reportes/listas/*.php ✅
/reportes/analisis/v1.0.0/* ✅
docs.zonasaridas.com.ar (Grav) ✅ (configurar tema Learn2)

Referencias