Theming

El widget se personaliza con dos mecanismos complementarios:

1. Variables CSS --nrn-* dentro del Shadow DOM — ~30 tokens en categorías surface, text, border, primary, secondary, accent, radius, shadow, transition, z-index y layout.
2. StyleOverrides desde la configuración (config.styles) — sobre-escribe cualquier subconjunto de las variables. Acepta hex (#06b6d4), rgb (rgb(6 182 212)) o RGB-triplet (6 182 212).

Como el widget vive en un Shadow DOM, los estilos del host no entran y los del widget no salen. Esto es deliberado: garantiza paridad visual entre tiendas y elimina conflictos con frameworks CSS del host (Bootstrap, Tailwind del tema, etc.).

Formato RGB-triplet

El widget guarda los colores en el formato R G B (sin coma) para permitir composición con rgb y alpha runtime:

:host, .neuroon-widget {
  --nrn-primary: 6 182 212;        /* cyan-500 */
  --nrn-surface-base: 255 255 255; /* white */
}

.button {
  background-color: rgb(var(--nrn-primary));
  /* alpha dinámico sin tener que redeclarar el color */
  box-shadow: 0 0 0 4px rgb(var(--nrn-primary) / 0.18);
}

Si pasas un hex (#06b6d4) en StyleOverrides, el widget lo convierte automáticamente al formato RGB-triplet.

Override por tema

NeuroonWidget.init({
  /* … */
  styles: {
    light: {
      primary: '#06b6d4',
      surfaceBase: '#ffffff',
      textPrimary: '#0f172a',
    },
    dark: {
      primary: '#22d3ee',
      surfaceBase: '#0f172a',
      textPrimary: '#f8fafc',
    },
  },
})

El widget detecta la forma con isThemedStyles y aplica el bloque correspondiente al tema activo.

Cuando el usuario cambia de tema (porque el sistema operativo cambia o el host emite neuroon:setTheme), el widget re-inyecta los overrides del tema activo en injectCustomStyles.

Override en caliente

Una vez montado, puedes invocar widget.setStyles({...}) en cualquier momento para refrescar los estilos sin re-montar el árbol. Internamente lanza injectCustomStyles con el tema actual.

Categorías de variables

Categoría	Prefijo	Ejemplos
Superficies	--nrn-surface-*	surface-base, surface-elevated, surface-overlay, surface-hover
Texto	--nrn-text-*	text-primary, text-secondary, text-muted, text-disabled
Bordes	--nrn-border-*	border-default, border-emphasis, border-subtle
Marca primaria	--nrn-primary*	primary, primary-light, primary-dark
Marca secundaria	--nrn-secondary*	secondary, secondary-light, secondary-dark
Accent	--nrn-accent-*	accent-purple, accent-emerald, accent-amber
Semánticas	—	--nrn-success, --nrn-error, --nrn-warning
Tipografía	--nrn-font-*	font-family, font-size-{xs..2xl}
Spacing	--nrn-spacing-*	xs, sm, md, lg, xl
Radius	--nrn-radius-*	sm, md, lg, xl, 2xl, full
Shadow	--nrn-shadow-*	sm, md, lg, xl
Transición	--nrn-transition-*	fast, base, slow
Z-index	--nrn-z-*	dropdown, sticky, modal-backdrop, modal, tooltip
Layout	—	--nrn-container-max-width, --nrn-drawer-width, --nrn-dropdown-max-height…

Tabla exhaustiva con defaults light/dark en Reference → Variables CSS. Mapping StyleOverrides → CSS var definido.

Ejemplo end-to-end

<div id="neuroon-search"></div>
<script>
  window.NeuroonWidget = window.NeuroonWidget || {}
</script>
<script
  src="https://cdn.neuroon.ai/widget@0.9.10/widget.js"
  data-token="WIDGET_TOKEN"
  data-container="#neuroon-search"
  data-theme="auto"
  defer
></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    if (!window.NeuroonWidget?.getInstance) return
    const w = window.NeuroonWidget.getInstance('#neuroon-search')
    w?.setStyles({
      light: {
        primary: '#0f766e',
        primaryLight: '#14b8a6',
        radiusLg: '0.5rem',
        fontFamily: '"Inter", system-ui, sans-serif',
      },
      dark: {
        primary: '#5eead4',
        surfaceBase: '#031c1a',
        textPrimary: '#ecfeff',
      },
    })
  })
</script>

Detección automática del host (theme: 'auto')

Con theme: 'auto' (default), el widget consulta window.matchMedia('(prefers-color-scheme: dark)') al montarse y se suscribe a sus cambios. Cada cambio dispara internamente un CustomEvent('neuroon-theme-change') que re-inyecta los overrides.

Forzar tema desde el host

Si el host quiere imponer el tema (p. ej. WooCommerce admin con preview), envía un postMessage:

const iframe = document.querySelector('iframe.neuroon-preview')
iframe.contentWindow.postMessage({
  type: 'neuroon:setTheme',
  theme: 'dark',  // 'light' | 'dark' | 'auto'
}, '*')

Próximas lecturas

• Reference → Variables CSS — tabla exhaustiva con defaults.
• Configuración — formato StyleOverrides.
• Eventos del widget — neuroon-theme-change y neuroon:setTheme.