Tokens Shine — Variantes CSS para datos-shine=1|2

Propósito

Los tokens Shine son un conjunto de sobrecargas CSS que se aplican cuando el usuario activa el modo brillo (Shine) en la UI. Se definen en static/css/variables.css mediante selectores :root[data-shine="1"] y :root[data-shine="2"], y redefinen aproximadamente 9 tokens CSS principales para crear un efecto de aclarado/brillo sin necesidad de filter ni backdrop-filter.

Introduced in v1.66.3 para reemplazar el mecanismo anterior que hundía rendimiento.

Estructura

Ubicación en código

Archivo: static/css/variables.css
Líneas: ~80-102 (bloque comentado /* SHINE ... */)
Selectores:

:root[data-shine="1"] — Nivel 1 (brillo moderado)
:root[data-shine="2"] — Nivel 2 (brillo intenso)

Tokens redefinidos (nivel de brillo)

Token	Nivel 0 (base)	Nivel 1	Nivel 2
`--bg-color`	`color-mix(in srgb, #0a0a0a 92%, transparent)`	`color-mix(in srgb, #161616 92%, transparent)`	`color-mix(in srgb, #242424 92%, transparent)`
`--bg-color-solid`	`#0a0a0a`	`#131313`	`#202020`
`--card-bg`	`rgba(20, 20, 20, 0.95)`	`rgba(31, 31, 31, 0.95)`	`rgba(45, 45, 45, 0.95)`
`--panel-bg`	`rgba(20, 20, 20, 0.95)`	`rgba(31, 31, 31, 0.95)`	`rgba(45, 45, 45, 0.95)`
`--bg-tertiary`	`#1a1a1a`	`#282828`	`#363636`
`--card-hover`	`#262626`	`#2e2e2e`	`#3d3d3d`
`--border-color`	`#444444`	`#555555`	`#666666`
`--text-secondary`	`#a0a0a0`	`#c2c2c2`	`#d4d4d4`
`--text-muted`	`#666666`	`#7d7d7d`	`#949494`

Patrón de desplazamiento

Cada token desplazado sigue un gradiente de luminosidad hacia arriba (más claro):

Fondos: +~15-20% de luminosidad cada nivel
Bordes: +~20-25% de luminosidad (más contraste visual)
Texto secundario: +~30% de claridad (legibilidad mejorada)

Mecanismo de aplicación

Cuándo se aplican

Usuario abre configuración UI → menú Shine
Selecciona nivel (0=apagado, 1=moderado, 2=intenso)

JavaScript en static/js/base.js, función applyShine():

if (i > 0) {
    document.documentElement.dataset.shine = String(i);
} else {
    delete document.documentElement.dataset.shine;
}

El navegador aplica los selectores CSS :root[data-shine="1"] o :root[data-shine="2"]
Todos los elementos que hereden las variables CSS de :root se aclaran

Persistencia

Se guarda en localStorage bajo 'shine' (mediante base.js)
Se restaura al cargar la página

Cobertura actual

~70-80% de superficies responden a Shine:

✅ Cards principales
✅ Paneles de contenido
✅ Fondos de secciones
✅ Bordes visibles
❌ Componentes legacy con hex inline
❌ Estilos @layer anteriores a la tokenización
❌ Valores background-color: #xxx hardcodeados en templates

Crecimiento: Cada migración de hex → token en la Iniciativa UI (#211) incrementa automáticamente la cobertura.

Limitaciones y gotchas

1. Cobertura parcial (“patchiness”)

En modo Shine nivel 2, algunas zonas heredadas pueden verse desemparejadas (más claras/oscuras que otras). Esto es esperado y temporal.

2. No afecta a `filter` aplicado en otros elementos

Si un componente individual tiene filter: brightness(…) en su CSS, el token Shine no lo sobrescribe. Solución: migrar esos estilos a tokens.

3. `backdrop-filter` sigue existiendo

Algunos elementos legados pueden aún tener backdrop-filter definido. Los tokens Shine no los tocan — solo redefinen CSS variables. Si quieres que un backdrop-filter también responda a Shine, deberás cambiar su sintaxis.

Mejoras futuras

Tokens específicos por modo oscuro/claro: Actualmente solo oscuro. Fase 2 puede añadir :root[data-shine="1"][data-theme="light"]
Shine animado: En lugar de pasos discretos (0/1/2), interpolar suavemente con transiciones CSS
Shine por zona: Aplicar brillo diferente a diferentes secciones (p. ej. panel izquierdo vs. editor)

Véase también

[[feature—ui—shine-tokens-v1663]]
[[decision—20260806—shine-architecture]]
[[concept—crearack-tech—design-system]]
[[entity—static—js—base-applyshine]]
[[feature—ui—iniciativa-ui-fase-2]]