analiticaNucleo/nuxt4-app/docs/THEME_CUSTOMIZATION.md

Sistema de Colores Personalizables - Analítica Núcleo

Introducción

Analítica Núcleo cuenta con un sistema de temas completamente personalizable que permite ajustar los colores de la interfaz según tus preferencias. El sistema está basado en variables CSS que se pueden modificar desde la página de Configuración.

Acceso al Configurador de Tema

1. Navega a Configuración desde el sidebar
2. O accede directamente a: https://analitica.nucleoriofrio.com/settings
3. Busca la sección "Tema y Apariencia"

Variables de Color Disponibles

El sistema utiliza 8 variables CSS principales que controlan toda la apariencia de la aplicación:

1. Fondo Principal (--brand-bg)

• Default: #14100b
• Uso: Color de fondo principal de toda la aplicación
• Afecta: Fondo del body, áreas principales de contenido
• Recomendación: Debe ser el color más oscuro del tema para dark mode

2. Fondo Secundario / Surface (--brand-surface)

• Default: #1f180f
• Uso: Color de fondo para elementos elevados (cards, sidebar, modales)
• Afecta: Sidebar, tarjetas, paneles, scrollbar
• Recomendación: Ligeramente más claro que el fondo principal (5-10% más luminoso)

3. Color de Bordes (--brand-border)

• Default: #3a2a16
• Uso: Bordes de elementos, separadores, divisores
• Afecta: Bordes de inputs, cards, tablas, divisores
• Recomendación: Debe tener suficiente contraste con surface pero no ser demasiado agresivo

4. Color Primario (--brand-primary)

• Default: #e0c080
• Uso: Color principal de la marca, elementos interactivos en estado normal
• Afecta: Botones primarios, enlaces, iconos destacados, texto de navegación activa
• Recomendación: Color distintivo de tu marca, debe tener buen contraste sobre fondos oscuros

5. Color Primario Fuerte (--brand-primary-strong)

• Default: #c08040
• Uso: Variante más intensa del color primario
• Afecta: Scrollbar thumb, elementos en estado hover/focus
• Recomendación: Versión más saturada o más oscura del color primario (15-20% más oscuro)

6. Color de Acento (--brand-accent)

• Default: #ffe0a0
• Uso: Color para llamar la atención, notificaciones, badges
• Afecta: Badges, notificaciones, elementos con alta prioridad visual
• Recomendación: Color brillante y distintivo, versión más clara del primario

7. Color de Texto (--brand-text)

• Default: #fef9f0
• Uso: Color principal del texto
• Afecta: Todo el texto de la aplicación (títulos, párrafos, labels)
• Recomendación: Debe tener excelente contraste con el fondo (ratio WCAG AA mínimo 4.5:1)

8. Color de Texto Secundario (--brand-text-muted)

• Default: #d8c7a6
• Uso: Texto de menor jerarquía, descripciones, placeholders
• Afecta: Texto secundario, descripciones, hints, placeholders
• Recomendación: Versión menos prominente del texto principal (20-30% menos luminosidad)

Cómo Personalizar el Tema

Método 1: Interfaz Gráfica (Recomendado)

1. Accede a Configuración → Tema y Apariencia
2. Modifica los colores:
   • Usa el color picker (selector de color) para elegir visualmente
   • O ingresa el código hexadecimal manualmente (ej: #ff5733)
3. Activa "Vista previa en vivo" (opcional) para ver cambios en tiempo real
4. Revisa la vista previa de los colores en la sección inferior
5. Haz clic en "Guardar cambios" para aplicar y persistir la configuración

Método 2: Edición Manual (Avanzado)

Si eres desarrollador, puedes editar directamente el archivo CSS:

/* Archivo: nuxt4-app/app/assets/css/main.css */

:root {
  --brand-bg: #tu-color-aqui;
  --brand-surface: #tu-color-aqui;
  --brand-border: #tu-color-aqui;
  --brand-primary: #tu-color-aqui;
  --brand-primary-strong: #tu-color-aqui;
  --brand-accent: #tu-color-aqui;
  --brand-text: #tu-color-aqui;
  --brand-text-muted: #tu-color-aqui;
}

Nota: Los cambios manuales requieren rebuild y despliegue de la aplicación.

Guía de Buenas Prácticas

1. Mantén la Jerarquía de Luminosidad

Para un tema oscuro coherente, sigue este orden de luminosidad:

--brand-bg (más oscuro)
  ↓
--brand-surface
  ↓
--brand-border
  ↓
--brand-primary-strong
  ↓
--brand-primary
  ↓
--brand-text-muted
  ↓
--brand-accent
  ↓
--brand-text (más claro)

2. Asegura el Contraste de Accesibilidad

Mínimo WCAG AA:

• Texto normal: ratio de contraste ≥ 4.5:1
• Texto grande: ratio de contraste ≥ 3:1

Recomendado WCAG AAA:

• Texto normal: ratio de contraste ≥ 7:1
• Texto grande: ratio de contraste ≥ 4.5:1

Herramientas útiles:

• WebAIM Contrast Checker
• Coolors Contrast Checker

3. Mantén la Coherencia Cromática

Opción A: Monocromático

• Usa diferentes tonos del mismo color base
• Ejemplo: Tema café actual (variaciones de marrón/beige)

Opción B: Análogo

• Usa colores adyacentes en la rueda cromática
• Ejemplo: Azul + Turquesa + Verde

Opción C: Complementario

• Color primario + su complementario como acento
• Ejemplo: Azul oscuro + Naranja para acentos

4. Prueba en Diferentes Condiciones

Después de personalizar, verifica:

• ✅ Legibilidad en diferentes páginas
• ✅ Contraste de botones y enlaces
• ✅ Visibilidad de bordes y separadores
• ✅ Claridad de la navegación activa
• ✅ Apariencia de modales y overlays

Casos de Uso Comunes

Tema "Noche Profunda" (Azul Oscuro)

Fondo Principal: #0a0e1a
Surface: #151a28
Bordes: #2d3748
Primario: #60a5fa
Primario Fuerte: #3b82f6
Acento: #93c5fd
Texto: #f0f4f8
Texto Muted: #cbd5e1

Tema "Bosque" (Verde Oscuro)

Fondo Principal: #0f1a14
Surface: #1a2820
Bordes: #2d4033
Primario: #86efac
Primario Fuerte: #4ade80
Acento: #bbf7d0
Texto: #f0fdf4
Texto Muted: #d1fae5

Tema "Carbón" (Gris Neutro)

Fondo Principal: #0f0f0f
Surface: #1a1a1a
Bordes: #333333
Primario: #a3a3a3
Primario Fuerte: #737373
Acento: #d4d4d4
Texto: #fafafa
Texto Muted: #d4d4d4

Restaurar Tema por Defecto

Si no te gusta la personalización o algo sale mal:

1. Ve a Configuración → Tema y Apariencia
2. Haz clic en "Restaurar por defecto"
3. Los colores volverán al tema café original

Esto también limpia la configuración guardada en localStorage.

Persistencia y Almacenamiento

¿Dónde se guarda mi tema personalizado?

Los cambios se guardan en el localStorage del navegador, lo que significa:

✅ Se mantiene entre sesiones - No necesitas reconfigurar cada vez ✅ Es por navegador - Cada navegador tiene su propia configuración ✅ Es local - No se sincroniza entre dispositivos

¿Qué pasa si limpio el caché?

Si limpias los datos del navegador (cookies, localStorage), el tema volverá a los valores por defecto.

¿Cómo uso el mismo tema en múltiples navegadores?

Opción 1 (Manual):

1. Anota los códigos hexadecimales de tu tema personalizado
2. Configúralos manualmente en cada navegador

Opción 2 (Futuro - Sincronización con Cuenta): En una futura versión, los temas se podrán guardar en el servidor vinculados a tu cuenta de usuario.

Integración con Componentes

Usar las variables en tu código

Si eres desarrollador y estás creando nuevos componentes, usa las variables CSS:

<template>
  <div class="mi-componente">
    <h1>Título con color de marca</h1>
    <p>Texto secundario</p>
  </div>
</template>

<style scoped>
.mi-componente {
  background: var(--brand-surface);
  border: 1px solid var(--brand-border);
  color: var(--brand-text);
}

h1 {
  color: var(--brand-primary);
}

p {
  color: var(--brand-text-muted);
}
</style>

Clases de Tailwind con variables

<div class="bg-[var(--brand-surface)] border-[var(--brand-border)] text-[var(--brand-text)]">
  Contenido
</div>

Solución de Problemas

Los cambios no se aplican

1. Verifica que hiciste clic en "Guardar cambios"
2. Recarga la página (F5 o Ctrl+R)
3. Si persiste, abre la consola del navegador (F12) y busca errores

Los colores se ven mal después de cambiarlos

1. Haz clic en "Restaurar por defecto"
2. Revisa las guías de buenas prácticas
3. Asegúrate de que el contraste sea suficiente

El tema no se guarda entre sesiones

1. Verifica que tu navegador permite localStorage
2. Revisa que no estés en modo incógnito/privado
3. Verifica que no tengas extensiones que bloqueen localStorage

Vista previa en vivo no funciona

1. Desactiva y reactiva el toggle
2. Si persiste, guarda los cambios manualmente
3. La vista previa es opcional, no afecta la funcionalidad principal

Arquitectura Técnica

Variables CSS y su Mapeo

El sistema usa dos capas de variables:

1. Variables de Marca (--brand-*): Definidas por el usuario 2. Variables de Nuxt UI (--ui-color-neutral-*): Mapeadas automáticamente

/* Definición en main.css */
:root {
  --brand-primary: #e0c080;

  /* Mapeo automático a Nuxt UI */
  --ui-color-neutral-500: var(--color-coffee-500);
}

Flujo de Aplicación

1. Usuario modifica color en UI
   ↓
2. JavaScript actualiza theme.value
   ↓
3. (Opcional) Vista previa en vivo → applyTheme()
   ↓
4. Usuario hace clic en "Guardar"
   ↓
5. localStorage.setItem('custom-theme', JSON.stringify(theme))
   ↓
6. applyTheme() → document.documentElement.style.setProperty()
   ↓
7. CSS variables actualizadas en :root
   ↓
8. Toda la UI se re-renderiza con nuevos colores

Compatibilidad

• ✅ Chrome 49+
• ✅ Firefox 31+
• ✅ Safari 9.1+
• ✅ Edge 15+
• ✅ Opera 36+

Roadmap Futuro

Funcionalidades planeadas:

• 🔄 Sincronización de tema con cuenta de usuario
• 🎨 Galería de temas predefinidos
• 📤 Exportar/Importar configuración de tema (JSON)
• 🌗 Soporte para modo claro (light mode)
• 🎯 Presets por categoría (Profesional, Creativo, Minimalista)
• 🔍 Vista previa de tema en todas las páginas
• 📊 Análisis automático de contraste y accesibilidad

Soporte

Si tienes problemas o sugerencias:

1. Documentación: Revisa este documento primero
2. Issues: Reporta problemas en el repositorio de Gitea
3. Contacto: Contacta al administrador del sistema

---

Última actualización: 2025-10-30 Versión del sistema: 1.0.0 Autor: Claude Code para Núcleo Río Frío