From bc02bc6bdeaa7396df7a0b08d0ee7d519c088176 Mon Sep 17 00:00:00 2001 From: josedario87 Date: Thu, 30 Oct 2025 17:18:32 -0600 Subject: [PATCH] =?UTF-8?q?Docs:=20Crear=20documentaci=C3=B3n=20definitiva?= =?UTF-8?q?=20del=20sistema=20de=20temas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Crear THEME_SYSTEM.md como documento único y completo - Eliminar DEVELOPER_GUIDE.md y THEME_CUSTOMIZATION.md (desactualizados) - Actualizar README.md con referencia al nuevo documento - Incluye arquitectura, variables, reglas, ejemplos y troubleshooting - Documentación clara para usuarios y desarrolladores --- nuxt4-app/README.md | 28 +- nuxt4-app/docs/DEVELOPER_GUIDE.md | 419 ---------------- nuxt4-app/docs/THEME_CUSTOMIZATION.md | 368 --------------- nuxt4-app/docs/THEME_SYSTEM.md | 655 ++++++++++++++++++++++++++ 4 files changed, 672 insertions(+), 798 deletions(-) delete mode 100644 nuxt4-app/docs/DEVELOPER_GUIDE.md delete mode 100644 nuxt4-app/docs/THEME_CUSTOMIZATION.md create mode 100644 nuxt4-app/docs/THEME_SYSTEM.md diff --git a/nuxt4-app/README.md b/nuxt4-app/README.md index 7a001f4..0e8d46a 100644 --- a/nuxt4-app/README.md +++ b/nuxt4-app/README.md @@ -13,24 +13,30 @@ Panel de administración y monitoreo empresarial para Núcleo Río Frío, constr ## Sistema de Temas -Analítica Núcleo cuenta con un **sistema de temas completamente personalizable** que permite ajustar los colores de la interfaz según tus preferencias. +Analítica Núcleo cuenta con un **sistema de temas completamente personalizable** que permite ajustar todos los colores de la interfaz en tiempo real. + +### Características + +- ✅ 8 variables de color personalizables +- ✅ 4 temas predefinidos: Café, Azul, Verde, Carbón +- ✅ Personalización individual con selector visual +- ✅ Persistencia en localStorage +- ✅ Exportar/importar temas en JSON +- ✅ Integración completa con Nuxt UI ### Para Usuarios -- Accede a **Configuración** (`/settings`) para personalizar el tema -- Elige entre 4 temas predefinidos: Café, Azul, Verde, Carbón -- O personaliza cada color individualmente con el selector visual -- Exporta/importa temas para compartir o hacer backup - -📖 **Documentación completa:** [THEME_CUSTOMIZATION.md](./docs/THEME_CUSTOMIZATION.md) +Accede a **Configuración** (`/settings`) para personalizar el tema de la aplicación. ### Para Desarrolladores -- Usa siempre variables CSS (`--brand-*`) en lugar de colores hardcoded -- Aprovecha las clases utilitarias (`.brand-card`, `.brand-shell`, etc.) -- Utiliza el composable `useTheme()` para manipular temas programáticamente +**REGLAS OBLIGATORIAS:** +- ✅ Usa **SIEMPRE** variables CSS (`--brand-*`) +- ✅ Usa clases utilitarias (`.brand-card`, `.brand-shell`, etc.) +- ❌ **NUNCA** uses colores hardcoded (`#ffffff`, etc.) +- ❌ **NUNCA** uses clases gray-scale (`bg-gray-900`, etc.) -📖 **Guía de desarrollo:** [DEVELOPER_GUIDE.md](./docs/DEVELOPER_GUIDE.md) +📖 **Documentación completa:** [THEME_SYSTEM.md](./docs/THEME_SYSTEM.md) Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. diff --git a/nuxt4-app/docs/DEVELOPER_GUIDE.md b/nuxt4-app/docs/DEVELOPER_GUIDE.md deleted file mode 100644 index dd0c4aa..0000000 --- a/nuxt4-app/docs/DEVELOPER_GUIDE.md +++ /dev/null @@ -1,419 +0,0 @@ -# Guía de Desarrollo - Sistema de Temas - -## Introducción - -Esta guía está dirigida a desarrolladores que trabajan en Analítica Núcleo y necesitan entender cómo funciona el sistema de temas y cómo mantener la consistencia visual en toda la aplicación. - -## Principios Fundamentales - -### 1. Siempre Usa Variables CSS - -**✅ CORRECTO:** -```vue -
- Contenido -
-``` - -**❌ INCORRECTO:** -```vue -
- Contenido -
-``` - -**❌ INCORRECTO:** -```vue -
- Contenido -
-``` - -### 2. Usa las Clases Utilitarias de Marca - -Para elementos comunes, usa las clases predefinidas en lugar de duplicar estilos: - -```vue - -
-

Título

-
-
- - -
-

Título

-
-
-``` - -## Variables de Tema Disponibles - -| Variable CSS | Uso | Ejemplo | -|--------------|-----|---------| -| `--brand-bg` | Fondo principal de la aplicación | `bg-[var(--brand-bg)]` | -| `--brand-surface` | Fondos de elementos elevados (cards, modales) | `bg-[var(--brand-surface)]` | -| `--brand-border` | Bordes de elementos | `border-[var(--brand-border)]` | -| `--brand-primary` | Color principal (enlaces, botones) | `text-[var(--brand-primary)]` | -| `--brand-primary-strong` | Variante más intensa del primario | `bg-[var(--brand-primary-strong)]` | -| `--brand-accent` | Color de acento para highlights | `text-[var(--brand-accent)]` | -| `--brand-text` | Texto principal | `text-[var(--brand-text)]` | -| `--brand-text-muted` | Texto secundario/menos prominente | `text-[var(--brand-text-muted)]` | - -## Clases Utilitarias de Marca - -### `.brand-shell` -Contenedor principal para layouts con gradiente radial. - -```vue -
- -
-``` - -### `.brand-card` -Tarjetas con estilos consistentes. - -```vue -
-

Título de la Card

-

Contenido

-
-``` - -### `.brand-divider` -Divisor horizontal decorativo. - -```vue -
-``` - -### `.brand-chip` y `.brand-pill` -Para pequeños tags o badges. - -```vue -Estado -Badge -``` - -### `.brand-table` -Estilos para tablas. - -```vue - - -
-``` - -## Patrones de Uso Común - -### Cards con Bordes y Sombras - -```vue - - - -

- Descripción del contenido -

- -``` - -### Botones con Hover Personalizado - -```vue - -``` - -### Inputs y Formularios - -```vue - -``` - -### Links con Hover - -```vue - - Ver perfil → - -``` - -### Personalización de Componentes Nuxt UI - -Muchos componentes de Nuxt UI aceptan la prop `:ui` para personalización: - -```vue - - Botón Personalizado - -``` - -## Composable `useTheme()` - -Para manipular el tema programáticamente, usa el composable `useTheme()`: - -```vue - -``` - -## Checklist Pre-Commit - -Antes de hacer commit de tu código, verifica: - -- [ ] **No hay colores hardcoded** (`#ffffff`, `#000000`, etc.) -- [ ] **No hay clases gray-scale genéricas** (`bg-gray-900`, `text-gray-500`, etc.) -- [ ] **Todos los fondos usan** `--brand-bg` o `--brand-surface` -- [ ] **Todos los bordes usan** `--brand-border` -- [ ] **Todo el texto usa** `--brand-text` o `--brand-text-muted` -- [ ] **Los elementos interactivos usan** `--brand-primary` o `--brand-accent` -- [ ] **Los hover states usan transparencias** (ej: `hover:bg-[var(--brand-primary)]/10`) -- [ ] **Se usan clases utilitarias** cuando sea posible (`.brand-card`, `.brand-shell`, etc.) - -## Casos Especiales - -### Colores Semánticos (Success, Error, Warning) - -Para colores que NO son parte del tema (éxito, error, advertencia), puedes usar colores de Tailwind: - -```vue - -
Éxito
-
Error
-
Advertencia
-
Info
- - -
- Operación exitosa -
-``` - -### Iconos - -Los iconos deben usar colores del tema: - -```vue - - - - - - - - -``` - -### Imágenes y Avatares con Bordes - -```vue - - - -``` - -### Hover y Focus States - -Siempre usa transparencias para hover states para que funcionen con cualquier tema: - -```vue - - - - - -``` - -## Ejemplos de Migración - -### Antes (Incorrecto) - -```vue - -``` - -### Después (Correcto) - -```vue - -``` - -## Errores Comunes y Soluciones - -### Error 1: Mezclar Variables con Hardcoded Colors - -**❌ No hagas esto:** -```vue -
- Contenido -
-``` - -**✅ Haz esto:** -```vue -
- Contenido -
-``` - -### Error 2: No Considerar el Contraste - -Asegúrate de que el texto tenga suficiente contraste sobre su fondo: - -**❌ Mal contraste:** -```vue -
- Texto importante -
-``` - -**✅ Buen contraste:** -```vue -
- Texto importante -
-``` - -### Error 3: Duplicar Estilos en Lugar de Usar Clases - -**❌ Duplicación:** -```vue -
- Card 1 -
-
- Card 2 -
-``` - -**✅ Reutilización:** -```vue -
Card 1
-
Card 2
-``` - -## Testing del Tema - -Para probar que tu componente respeta el tema: - -1. Ve a `/settings` -2. Cambia el tema a "Azul Corporativo" o "Verde Natural" -3. Navega a tu componente -4. Verifica que todos los colores cambien correctamente -5. Verifica que no haya elementos con colores hardcoded que no cambiaron - -## Recursos Adicionales - -- **Documentación del usuario:** `THEME_CUSTOMIZATION.md` -- **Composable de temas:** `app/composables/useTheme.ts` -- **Variables CSS:** `app/assets/css/main.css` -- **Configuración de Nuxt UI:** `app.config.ts` - -## Preguntas Frecuentes - -### ¿Puedo usar colores de Tailwind como `bg-blue-500`? - -Solo para estados semánticos (éxito, error, advertencia) que NO forman parte del tema. Para todo lo demás, usa las variables de tema. - -### ¿Cómo personalizo un componente de Nuxt UI? - -Usa la prop `:ui` con las variables de tema: - -```vue - - Contenido - -``` - -### ¿Qué hago si necesito un color que no está en el tema? - -Primero pregunta: ¿realmente necesito un color nuevo, o puedo usar uno existente? Si es absolutamente necesario, propón agregar una nueva variable al sistema de temas en lugar de hardcodear el color. - -### ¿Cómo manejo dark mode? - -No necesitas manejarlo manualmente. Las variables CSS ya están optimizadas para dark mode. Solo usa las variables y funcionará automáticamente. - ---- - -**Última actualización:** 2025-10-30 -**Mantenedor:** Claude Code para Núcleo Río Frío -**Versión:** 1.0.0 diff --git a/nuxt4-app/docs/THEME_CUSTOMIZATION.md b/nuxt4-app/docs/THEME_CUSTOMIZATION.md deleted file mode 100644 index e15122d..0000000 --- a/nuxt4-app/docs/THEME_CUSTOMIZATION.md +++ /dev/null @@ -1,368 +0,0 @@ -# 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: - -```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](https://webaim.org/resources/contrastchecker/) -- [Coolors Contrast Checker](https://coolors.co/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: - -```vue - - - -``` - -### Clases de Tailwind con variables - -```vue -
- Contenido -
-``` - -## 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](#guía-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 - -```css -/* 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 diff --git a/nuxt4-app/docs/THEME_SYSTEM.md b/nuxt4-app/docs/THEME_SYSTEM.md new file mode 100644 index 0000000..3eb21f2 --- /dev/null +++ b/nuxt4-app/docs/THEME_SYSTEM.md @@ -0,0 +1,655 @@ +# Sistema de Temas - Analítica Núcleo + +> **Documentación definitiva del sistema de temas personalizable** +> Versión: 2.0 | Última actualización: 2025-10-30 + +## Índice + +1. [Introducción](#introducción) +2. [Arquitectura del Sistema](#arquitectura-del-sistema) +3. [Variables CSS Disponibles](#variables-css-disponibles) +4. [Reglas de Uso Obligatorias](#reglas-de-uso-obligatorias) +5. [Clases Utilitarias](#clases-utilitarias) +6. [Composable useTheme()](#composable-usetheme) +7. [Ejemplos de Uso](#ejemplos-de-uso) +8. [Integración con Nuxt UI](#integración-con-nuxt-ui) +9. [Casos Especiales](#casos-especiales) +10. [Troubleshooting](#troubleshooting) + +--- + +## Introducción + +Analítica Núcleo cuenta con un sistema de temas completamente dinámico que permite personalizar todos los colores de la interfaz en tiempo real. Los cambios se aplican instantáneamente a todos los componentes de la aplicación. + +**Características principales:** +- ✅ 8 variables de color personalizables +- ✅ 4 temas predefinidos (Café, Azul, Verde, Carbón) +- ✅ Persistencia en localStorage +- ✅ Vista previa en tiempo real +- ✅ Exportar/importar temas en JSON +- ✅ Integración completa con Nuxt UI + +--- + +## Arquitectura del Sistema + +### Flujo de Datos + +``` +Usuario modifica tema en /settings + ↓ + useTheme() composable + ↓ + Actualiza variables CSS (--brand-*) + ↓ + Variables --ui-color-neutral-* mapeadas automáticamente + ↓ + Todos los componentes se actualizan instantáneamente +``` + +### Archivos Clave + +| Archivo | Propósito | +|---------|-----------| +| `app/assets/css/main.css` | Definición de variables CSS y clases utilitarias | +| `app/composables/useTheme.ts` | Lógica del sistema de temas | +| `app/pages/settings.vue` | Interfaz de configuración | + +--- + +## Variables CSS Disponibles + +### Variables de Tema (`--brand-*`) + +Estas son las **ÚNICAS** variables que debes usar en tu código: + +| Variable | Uso | Ejemplo de valor | +|----------|-----|------------------| +| `--brand-bg` | Fondo principal de la app | `#14100b` | +| `--brand-surface` | Fondos de cards, modales, elementos elevados | `#1f180f` | +| `--brand-border` | Bordes de todos los elementos | `#3a2a16` | +| `--brand-primary` | Color principal para enlaces, títulos destacados | `#e0c080` | +| `--brand-primary-strong` | Variante más intensa del primario | `#c08040` | +| `--brand-accent` | Highlights, elementos de énfasis | `#ffe0a0` | +| `--brand-text` | Texto principal (alta legibilidad) | `#fef9f0` | +| `--brand-text-muted` | Texto secundario, descripciones | `#d8c7a6` | + +### Variables de Nuxt UI (`--ui-color-neutral-*`) + +⚠️ **NO uses estas variables directamente**. Están mapeadas automáticamente a `--brand-*` en `main.css`. + +**Mapeo actual (NO modificar):** +```css +--ui-color-neutral-50: var(--brand-text); /* Texto más claro */ +--ui-color-neutral-100: var(--brand-text-muted); /* Texto secundario */ +--ui-color-neutral-200: var(--brand-primary); /* Primario claro */ +--ui-color-neutral-300: var(--brand-primary); /* Primario */ +--ui-color-neutral-400: var(--brand-primary-strong); /* Primario fuerte */ +--ui-color-neutral-500: var(--brand-border); /* Bordes */ +--ui-color-neutral-600: var(--brand-border); /* Bordes */ +--ui-color-neutral-700: var(--brand-surface); /* Surface */ +--ui-color-neutral-800: var(--brand-surface); /* Surface */ +--ui-color-neutral-900: var(--brand-bg); /* Fondo más oscuro */ +--ui-color-neutral-950: var(--brand-bg); /* Fondo */ +``` + +> **IMPORTANTE:** Nuxt UI usa la escala neutral de forma invertida en dark mode: +> - `neutral-50/100` → Colores claros (texto) +> - `neutral-900/950` → Colores oscuros (fondos) + +--- + +## Reglas de Uso Obligatorias + +### ✅ SIEMPRE Hacer + +1. **Usar variables CSS en lugar de colores hardcoded:** + ```vue + +
+ Contenido +
+ ``` + +2. **Usar clases utilitarias cuando existan:** + ```vue + +
+

Título

+
+ ``` + +3. **Usar transparencias para hover states:** + ```vue + + + ``` + +### ❌ NUNCA Hacer + +1. **NO usar colores hardcoded:** + ```vue + +
+ Contenido +
+ ``` + +2. **NO usar clases gray-scale genéricas:** + ```vue + +
+ Contenido +
+ ``` + +3. **NO mezclar variables con hardcoded:** + ```vue + +
+ Contenido +
+ ``` + +--- + +## Clases Utilitarias + +### `.brand-shell` +Contenedor principal con gradiente radial. + +```vue +
+ +
+``` + +### `.brand-card` +Tarjetas con estilos consistentes (gradiente, borde, sombra). + +```vue +
+

Título

+

Contenido

+
+``` + +### `.brand-divider` +Divisor horizontal decorativo. + +```vue +
+``` + +### `.brand-section-title` +Títulos de sección con color primario. + +```vue +

Mi Sección

+``` + +### `.brand-chip` / `.brand-pill` +Tags o badges pequeños. + +```vue +Estado +Badge +``` + +### `.brand-badge` +Badge con fondo primario sólido. + +```vue +3 +``` + +### `.brand-table` +Estilos para tablas. + +```vue + + ... + ... +
+``` + +--- + +## Composable useTheme() + +### Importar + +```typescript +const { + theme, + applyTheme, + saveTheme, + resetTheme, + exportTheme, + importTheme +} = useTheme() +``` + +### API + +#### `theme` (Ref) +Estado reactivo del tema actual. + +```typescript +interface ThemeColors { + bg: string + surface: string + border: string + primary: string + primaryStrong: string + accent: string + text: string + textMuted: string +} +``` + +#### `applyTheme(newTheme?: ThemeColors)` +Aplica el tema a las variables CSS del DOM. + +```typescript +applyTheme() // Aplica theme.value actual +applyTheme(customTheme) // Aplica un tema personalizado +``` + +#### `saveTheme()` +Guarda el tema actual en localStorage. + +```typescript +const success = saveTheme() +if (success) { + console.log('Tema guardado') +} +``` + +#### `resetTheme()` +Resetea al tema por defecto (Café). + +```typescript +resetTheme() +``` + +#### `exportTheme()` +Exporta el tema actual como JSON string. + +```typescript +const jsonTheme = exportTheme() +await navigator.clipboard.writeText(jsonTheme) +``` + +#### `importTheme(jsonString: string, autoSave: boolean = false)` +Importa un tema desde JSON string. + +```typescript +const success = importTheme(jsonString, true) // true = guardar automáticamente +``` + +--- + +## Ejemplos de Uso + +### Ejemplo 1: Card Básica + +```vue + +``` + +### Ejemplo 2: Botón con Hover + +```vue + +``` + +### Ejemplo 3: Input Personalizado + +```vue + +``` + +### Ejemplo 4: Link con Hover + +```vue + +``` + +### Ejemplo 5: Iconos + +```vue + +``` + +### Ejemplo 6: Manipular Tema Programáticamente + +```vue + + + +``` + +--- + +## Integración con Nuxt UI + +### Componentes que Respetan el Tema Automáticamente + +Los siguientes componentes de Nuxt UI **NO necesitan customización** porque usan `--ui-color-neutral-*` internamente: + +- `UButton` (con `color="neutral"`) +- `UBadge` (con `color="neutral"`) +- `UInput` (parcialmente) +- `UTextarea` (parcialmente) +- `USelect` (parcialmente) +- Componentes de navegación (sidebar, navbar) + +### Componentes que Necesitan `:ui` Prop + +Para estos componentes, debes especificar colores explícitamente: + +#### UCard + +```vue + + + +``` + +#### UModal + +```vue + + + +``` + +#### UDropdown + +```vue + + + +``` + +--- + +## Casos Especiales + +### Colores Semánticos (Success, Error, Warning) + +Para estados semánticos, **SÍ puedes usar colores fijos de Tailwind** porque no forman parte del tema personalizable: + +```vue + +``` + +### Imágenes y Avatares + +```vue + +``` + +### Gradientes + +```vue + +``` + +--- + +## Troubleshooting + +### Problema 1: Texto Invisible + +**Síntoma:** El texto no se ve en algunos componentes. + +**Causa:** Estás usando un color de fondo donde debería ir un color de texto. + +**Solución:** +```vue + +
+ + +
+``` + +### Problema 2: Componentes No Cambian con el Tema + +**Síntoma:** Algunos componentes mantienen colores fijos cuando cambias de tema. + +**Causa:** Estás usando colores hardcoded o clases gray-scale. + +**Solución:** Reemplaza todos los colores fijos con variables `--brand-*`. + +### Problema 3: UCard con Fondo Incorrecto + +**Síntoma:** UCard tiene un fondo que no corresponde al tema. + +**Causa:** Falta especificar la prop `:ui`. + +**Solución:** +```vue + + + +``` + +### Problema 4: Hover No Se Ve + +**Síntoma:** Los hover effects no son visibles. + +**Causa:** Estás usando colores sólidos en lugar de transparencias. + +**Solución:** +```vue + +