Runtime Theme API
Usa el contrato de theming runtime de Nuvex UI para inspeccionar, cambiar, persistir y extender el tema activo sin reconstruir por tu cuenta el flujo base del sistema.
Antes de empezar
- Ya entiendes que light y dark son los temas baseline integrados de la libreria.
- Quieres operar el tema activo desde codigo de app en lugar de redefinir todo el sistema visual.
- Nuvex UI ya esta instalado y renderizando correctamente en tu proyecto.
Como se resuelve el tema inicial
La libreria primero intenta restaurar un tema valido desde storage, luego considera la preferencia del sistema y al final cae al fallback configurado o al baseline built-in.
Si un valor almacenado no existe en el registro real de temas, la libreria lo descarta y continua con el siguiente paso de resolucion.
app/plugins/nuvex-ui.ts
Inspecciona el estado del tema
Usa el estado runtime que Nuvex UI ya expone en lugar de leer atributos del DOM o de mantener un registro paralelo de temas en tu app.
components/ThemeInspector.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemeInspector.vue <script setup>
Cambia el tema activo
Usa estas operaciones cuando la app necesita fijar un tema conocido, alternar entre opciones o volver al fallback de la libreria.
setTheme ignora nombres desconocidos y conserva el estado valido actual, pero ese caso sigue siendo un error de integracion que tu app debe tratar.
components/AppThemeToggle.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemeResetButton.vue <script setup>
Persiste la eleccion del usuario
Nuvex UI ya soporta persistencia por llave o mediante un adaptador custom, asi que aqui se trata de conectar el contrato y no de reinventar la persistencia.
Si tu app necesita persistencia de tema consciente de SSR, conecta aqui un storage custom y deja el flujo especifico del framework para la guia de integracion.
app/plugins/nuvex-ui.ts
app/plugins/nuvex-ui.ts
Controla la salida al DOM
La API runtime no solo mantiene estado. Tambien escribe el tema activo en el DOM mediante un atributo configurable y ajusta color-scheme cuando corresponde.
app/plugins/nuvex-ui.ts
Emite tokens del tema como CSS variables
Habilita esta salida cuando el tema runtime activo tambien necesita publicar valores de token para consumo CSS sin montar otra capa puente en tu app.
Esta opcion publica tokens del tema runtime activo. No reemplaza la decision de cuando un cambio pertenece a tokens frente a overrides CSS.
app/plugins/nuvex-ui.ts
assets/styles/app.css
Registra temas en runtime
Usa el registro runtime cuando la app necesita agregar o quitar variantes nombradas durante la ejecucion sin alterar el contrato baseline de los built-ins.
light y dark forman parte del baseline integrado de la libreria. No se pueden volver a registrar ni eliminar desde este contrato runtime.
components/ThemeRegistryDemo.vue <script setup>
Patrones de integracion en app
Cierra la pagina con patrones reales de uso que muestran como encaja el contrato runtime en UI de aplicacion sin infraestructura extra.
layouts/default.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemePreferenceGate.vue <script setup>
Errores runtime que conviene evitar
No son errores genericos de programacion. Aparecen cuando usas el contrato de theming en la capa equivocada o con supuestos incorrectos.
Resolver con runtime un problema de tokens
Si el cambio real es visual y estable, la siguiente pagina probablemente sea Design Tokens o CSS Variables, no otra rama runtime.
Suponer que cualquier string funciona
setTheme solo aplica nombres que ya estan registrados en el runtime de la libreria.
Intentar redefinir built-ins en runtime
light y dark forman parte del contrato baseline y no se tratan como temas descartables definidos por usuario.
Duplicar el registro en estado de app
Si availableThemes y getThemes() ya exponen la fuente de verdad, evita espejar esa lista en otro store sin una razon real.
Siguientes pasos recomendados
Continua con la pagina que mejor encaje con tu siguiente decision sobre comportamiento baseline, customizacion visual o alta de una nueva variante.