Modo oscuro que no parece barato — Sistema de tokens bien hecho

Cómo ocurre un modo oscuro barato (y cómo se manifiesta)

El modo oscuro que se ve barato tiene un conjunto consistente de modos de fallo. Puedes reconocerlos como un ingeniero en on-call reconoce un mal despliegue:
todo está “técnicamente funcionando”, pero las sensaciones son incorrectas y el canal de incidentes se está calentando.

Olor #1: Todo es el mismo gris

Si tu fondo, la superficie y las superficies elevadas están separadas por deltas mínimos (o deltas aleatorios), la interfaz se convierte en un charco plano. En modo claro,
a menudo puedes salirte con la tuya con elevaciones de superficie descuidadas porque las sombras y la luz ambiental hacen parte del trabajo. En modo oscuro, tus superficies deben
llevar la jerarquía.

Olor #2: El contraste del texto está bien, pero aún se lee mal

Las ratios de contraste de WCAG no garantizan comodidad. Las UIs oscuras pueden cumplir objetivos de contraste y aún producir halation—texto brillante que parece vibrar.
La solución no es “reducir contraste hasta que falle”, es dejar de usar blanco puro y negro puro, y controlar cómo escalonan tus neutros.

Olor #3: Los colores de marca se ven neón o sucios

Los acentos saturados sobre superficies oscuras pueden parecer carteles LED baratos. Por el contrario, si simplemente oscureces el mismo tono de marca, se convierte en un moretón.
Necesitas valores de token separados por tema para los acentos, con restricciones vinculadas al contraste y al brillo percibido, no a “multiplicar por 0.8”.

Olor #4: Los componentes “pierden el carácter” en estados límite

Hover, active, focus, disabled y error revelan si construiste un sistema o un collage. El modo oscuro es especialmente punitivo:
un anillo de foco que funcionó en modo claro puede desaparecer; el texto deshabilitado puede volverse indistinguible del normal; los bordes pueden parecer líneas accidentales.

Olor #5: Cada equipo de la app tiene su propia interpretación

Si los tokens existen pero cada producto los usa de forma diferente, eso no es theming; es “vocabulario compartido” sin significado compartido.
La solución son tokens semánticos mapeados desde primitivos, con uso previsto claro y guardrails.

Una verdad operacional: cuantas más apps tengas, más debes tratar el theming como una plataforma. No es “colores”. Es un contrato de compatibilidad.

Broma #1: El modo oscuro no es difícil porque los colores sean complicados. Es difícil porque tu organización trata “#121212” como una estrategia.

Hechos útiles y contexto histórico (para que dejes de repetir la historia)

• Los primeros “UIs oscuros” no eran elecciones estéticas. Muchos terminales eran texto claro sobre fondos oscuros porque las pantallas de fósforo y las limitaciones energéticas lo hacían práctico.
• “Invertir colores” ha estado fallando desde siempre. Las primeras herramientas de accesibilidad intentaron la inversión y se toparon con el caos en imágenes y colores de marca; el theming moderno todavía está limpiando eso.
• OLED cambió la conversación. Los píxeles oscuros pueden ahorrar energía en OLED; en LCD, el ahorro es menor y a veces insignificante según el brillo.
• Material Design popularizó la elevación estructurada. Normalizó pensar en superficies y capas en lugar de “fondo + algunas tarjetas”, lo que importa más en modo oscuro.
• Las ratios de contraste WCAG son matemática, no comodidad. Miden contraste de luminancia, no deslumbramiento percibido ni legibilidad a largo plazo.
• Los design tokens se volvieron una respuesta de estandarización. A medida que crecieron las bibliotecas de componentes, los equipos necesitaban una forma portátil y agnóstica a herramientas para codificar decisiones de diseño.
• La preferencia del sistema se volvió prioritaria. El prefers-color-scheme a nivel de SO convirtió el tema en una preocupación en tiempo de ejecución, no solo una elección en tiempo de compilación.
• “Modo oscuro en todas partes” creó deuda en imágenes/iconos. Íconos, ilustraciones y gráficos a menudo dependían de fondos claros implícitos; el theming forzó decisiones explícitas.

Si sacas una lección de la historia: cada vez que los equipos trataron el modo oscuro como “modo claro pero más oscuro”, terminaron construyendo una segunda interfaz de todos modos—solo que sin admitirlo.
Admítelo temprano. Construye el sistema.

El modelo de tokens: primitivos, semántica y componentes

Los sistemas de tokens fallan cuando están organizados como cubetas de pintura en lugar de como una API. Un buen sistema de tokens se ve aburrido porque es predecible.
Predecible es lo que quieres a las 2 a. m. cuando un hotfix no puede arriesgar regresiones visuales.

Capa 1: Tokens primitivos (materias primas)

Los tokens primitivos son tu paleta y medidas: pasos de escala de grises, tonos de marca, unidades de espaciado, radios, escalas tipográficas. Responden:
“¿Qué colores existen?” no “¿Dónde van?”

Reglas que mantienen los primitivos sanos:

• Usa pasos, no sensaciones. Define los neutrales como una escalera (por ejemplo, neutral-0…neutral-1000) con deltas de luminancia consistentes.
• Mantén los primitivos conscientes del tema. Puedes tener conjuntos primitivos separados para claro y oscuro (especialmente para neutros y acentos).
• Los primitivos no deben filtrarse al código de producto. Si el código de producto usa neutral-900 directamente, ya perdiste la consistencia.

Capa 2: Tokens semánticos (significado e intención)

Los tokens semánticos representan roles: bg, surface, text-primary, border-subtle, focus-ring,
danger, success, link.

La semántica responde: “¿Para qué sirve este token?” Un token semántico debe tener un significado estrecho y un contrato estable. Los valores pueden cambiar por tema y marca.
El significado no debería.

Opiniones firmes que te salvarán:

• Define un glosario de tokens semánticos. Escribe el uso previsto y “no usar para X”.
• Separa el contenido del contenedor. Los tokens de texto no deben reutilizarse para bordes porque alguien pensó “es el mismo gris”.
• Incluye tokens de interacción y estado. Hover/active/focus/disabled no son cosas posteriores; son donde el modo oscuro se rompe.
• Incluye semántica de visualización de datos temprano. Los gráficos se vuelven ilegibles rápidamente en modo oscuro si no predefines tokens para ejes, cuadrículas, series y tooltips.

Capa 3: Tokens de componente (ajuste de última milla)

Los tokens de componente son para casos donde un componente necesita ajuste especial sin contaminar la semántica global: p. ej., button-primary-bg,
tooltip-bg, modal-overlay.

El truco: los tokens de componente deberían referenciar tokens semánticos por defecto y solo divergir cuando haya una razón real.
Si cada componente define sus propios colores, has construido una segunda paleta con peor gobernanza.

Nombrado que no se pudre

Evita nombrar tokens por colores (blue-500) cuando te refieres a propósito (link). Nombra por intención. Siempre.
Si debes mantener nombres de color (para primitivos), mantenlos alejados del código de producto.

Un esquema de nombres práctico:

• Primitivos: color.neutral.0, color.neutral.900, color.brand.primary.600
• Semántica: color.bg, color.surface, color.text.primary, color.border.subtle
• Componentes: color.button.primary.bg, color.input.border.focus

Si prefieres propiedades personalizadas CSS, mapea a --color-bg, --color-text-primary, etc. Misma idea, menos puntos.

Comportamiento del color en UI oscuras: contraste, luminancia y por qué “invertir todo” falla

El modo oscuro no es simplemente “modo claro con hex diferentes”. Trabajas contra la percepción humana y la física del dispositivo.
Trátalo como planificación de capacidad: los números importan, pero la historia real está en la forma de la curva.

Elige “casi negro”, no negro

El negro puro (#000000) se ve duro en muchos contextos y exagera el contraste con el texto y los efectos de elevación. La mayoría de temas oscuros de alta calidad usan un casi-negro,
usualmente ligeramente matizado (frío o cálido) para sentirse intencional y reducir el banding.

Usa texto blanco levemente desaturado

El blanco puro sobre fondos oscuros puede causar halation: brillo percibido y fatiga visual. Usa un blanco off-white para texto primario y desciende para secundario y deshabilitado.
Mantén los pasos consistentes.

La elevación en modo oscuro se trata sobre todo de aclarar superficies

En modo claro, las superficies elevadas suelen recibir sombras más oscuras. En modo oscuro, las sombras no se leen igual; normalmente aclaras ligeramente la superficie elevada,
y usas sombras sutiles o bordes con moderación para señalar separación.

No reutilices la lógica de bordes del modo claro

Los bordes en modo claro suelen ser un poco más oscuros que la superficie. En modo oscuro, los bordes pueden necesitar ser un poco más claros que la superficie,
o desaparecen. Este es un error clásico de “copiar el mapeo de tokens”.

Los colores de acento necesitan ajuste por tema

El mismo color de marca puede verse distinto contra superficies oscuras. Generalmente necesitas:

• un acento ligeramente más brillante (mayor luminancia) para fondos oscuros,
• una variante de contorno/anillo de foco que siga siendo visible tanto sobre el acento como sobre el fondo,
• y una variante atenuada para fondos sutiles (badges, resaltados) que no parezca un moretón.

Una cita, porque sigue siendo cierta

“La esperanza no es una estrategia.” — Rick Page

Si tu tema depende de esperar que los componentes “probablemente se vean bien”, vas a enviar regresiones. Instruméntalo.

Una arquitectura de theming apta para producción

Quieres un sistema de theming que pueda hacer tres cosas sin drama:
(1) cambiar temas de forma fiable, (2) mantener componentes consistentes, (3) soportar múltiples marcas o productos sin bifurcar el mundo.

Decisión: ¿Dónde viven los tokens?

Pon los tokens en un paquete versionado único. Genera salidas para las plataformas que te importen (variables CSS, JSON, tipos TS).
La “fuente de la verdad” debe ser un formato, no tres copias editadas a mano.

Decisión: ¿Cómo se aplican los temas?

Usa un atributo raíz único y variables CSS:

• data-theme="light" y data-theme="dark" en <html> o <body>
• Define conjuntos de variables scopeados a ese atributo

Esto evita la “página medio-teemada” donde algún subárbol está atrapado con valores viejos. También lo hace medible: puedes afirmar que el atributo existe.

Decisión: ¿Cómo se mapean los tokens entre temas?

Trata el mapeo como una matriz. Cada token semántico debe tener un valor para cada tema (y para cada marca si es necesario). Si un token semántico no tiene
valor en modo oscuro, eso es una falla en tiempo de build, no una sorpresa en tiempo de ejecución.

Decisión: ¿Cómo manejas la preferencia del usuario y la persistencia?

Usa la preferencia del SO como predeterminada (prefers-color-scheme), pero persiste las elecciones explícitas del usuario. Hazlo determinista:

• Orden: override del usuario → preferencia almacenada → preferencia del SO → predeterminado
• Aplica el atributo de tema lo más pronto posible para evitar parpadeos

Rendimiento: prevenir el jank al cambiar tema

Cambiar tema toca estilos computados. DOMs grandes hacen esto costoso. Mantén los conjuntos de variables superficiales (scope raíz), evita estilos inline por componente,
y no animas todo durante un swap de tema.

Broma #2: Si tu toggle de tema anima 300 propiedades CSS, felicitaciones—has inventado un simulador de consumo de batería.

Pruebas: trata el tema como una superficie de lanzamiento

Un sistema de theming real tiene:

• tests de completitud de tokens (sin mapeos faltantes),
• pruebas de contraste para pares clave (texto/fondo, iconos/superficies, anillos de foco),
• tests de regresión visual para pantallas representativas,
• reglas de lint que impidan que el código de producto use primitivos directamente.

Flujos de trabajo y gobernanza: cómo evitar que los tokens se conviertan en un cajón de trastos

Los tokens fallan lentamente. Primero, un equipo “solo necesita un gris especial”. Luego otro equipo añade un hover “ligeramente diferente”. Seis meses después,
el modo oscuro parece una colcha de parches y nadie puede explicar por qué. La gobernanza no es burocracia; es cómo mantienes el sistema barato de operar.

Define propiedad y el camino de cambios

Elige un grupo pequeño (design systems + un ingeniero de producto) como mantenedores. Todos los demás presentan cambios mediante un proceso predecible:

• Request: ¿qué problema de UI estás resolviendo?
• Token semántico propuesto: ¿por qué merece existir?
• Mapping: valores para claro + oscuro (y marcas), incluyendo notas de contraste
• Plan de rollout: ¿cómo migramos usos antiguos?

Haz la “deriva semántica” observable

Crea un pequeño reporte de uso de tokens en CI:

• ¿Qué tokens semánticos están sin usar?
• ¿Qué primitivos son referenciados fuera del paquete de tokens?
• ¿Qué componentes definen colores personalizados en lugar de usar semántica?

Planifica migraciones como planificas migraciones de almacenamiento

Los ingenieros de almacenamiento aprenden esto pronto: no migras datos “solo cambiando la ruta.” Haces dual-write, validas, despliegas gradualmente.
Los tokens son similares. Introduce nuevos tokens semánticos, mapea, migra componentes, depreca los antiguos con advertencias y solo entonces elimínalos.

Detén los bugs de tema en el límite

Haz cumplir la regla: el código de producto consume solo tokens semánticos (o tokens de componente), no primitivos.
Si un equipo necesita una nueva tonalidad, eso es una solicitud de cambio de token, no un hack local.

Tareas prácticas con comandos: inspeccionar, medir, decidir (12+)

La forma más rápida de mejorar el modo oscuro es tratarlo como una superficie operacional. Mide primero. Luego decide.
A continuación hay tareas reales y ejecutables que puedes usar en un repo que almacena tokens y exporta variables CSS.
Mostraré comandos, salidas de ejemplo, qué significan y la decisión que tomas.

Tarea 1: Encontrar uso directo de tokens primitivos en código de producto

cr0x@server:~$ rg -n "neutral\.(?:[0-9]{1,4})|--color-neutral-[0-9]{1,4}" apps/ packages/
apps/web/src/components/Banner.css:14:  color: var(--color-neutral-50);
apps/admin/src/pages/Settings.tsx:92:  background: var(--color-neutral-950);

Significado de la salida: El código de producto está usando primitivos directamente, eludiendo la semántica.

Decisión: Abrir un issue de refactor: reemplazar por tokens semánticos (--color-text-secondary, --color-surface, etc.) y añadir una regla de lint para prevenir recurrencias.

Tarea 2: Verificar que cada token semántico tenga un valor en el tema oscuro

cr0x@server:~$ jq -r '.semantic | keys[]' tokens/semantic.json | wc -l
148

cr0x@server:~$ jq -r '.themes.dark.semantic | keys[]' tokens/theme-dark.json | wc -l
146

Significado de la salida: El tema oscuro le faltan 2 mapeos semánticos.

Decisión: Fallar el build hasta que las claves faltantes estén mapeadas. Los tokens faltantes en modo oscuro se convierten en “colores aleatorios” en tiempo de ejecución, y así es como ocurre lo barato.

Tarea 3: Listar las claves semánticas faltantes

cr0x@server:~$ comm -3 \
  <(jq -r '.semantic | keys[]' tokens/semantic.json | sort) \
  <(jq -r '.themes.dark.semantic | keys[]' tokens/theme-dark.json | sort)
color.focus.ring
color.table.row.hover

Significado de la salida: Dos roles carecen de definiciones para modo oscuro: focus ring y hover de fila de tabla.

Decisión: Definirlos explícitamente para oscuro. No “tomar prestado” mapeos de claro.

Tarea 4: Validar que las variables CSS existan en el artefacto construido

cr0x@server:~$ npm run build:css
...output...
dist/tokens.css  34.2kb

cr0x@server:~$ rg -n "--color-focus-ring" dist/tokens.css | head
211:  --color-focus-ring: #7aa2ff;

Significado de la salida: El token está presente en el CSS construido.

Decisión: Si falta, tu pipeline de build está eliminando tokens o el nombre difiere. Arregla el generador o la inconsistencia de nombres.

Tarea 5: Buscar definiciones de token duplicadas o conflictivas

cr0x@server:~$ rg -n "--color-text-primary:" dist/tokens.css
54:  --color-text-primary: #e7eaf0;
912: --color-text-primary: #f6f7fb;

Significado de la salida: El token está definido dos veces—probablemente dos scopes de tema solapados o un error de merge.

Decisión: Asegura que las variables estén scopeadas bajo [data-theme="dark"] y [data-theme="light"], no duplicadas en root.

Tarea 6: Confirmar que el scoping de tema sea correcto (atributo raíz solamente)

cr0x@server:~$ rg -n "\[data-theme=" dist/tokens.css | head -n 20
1:[data-theme="light"] {
401:[data-theme="dark"] {

Significado de la salida: Solo existen dos scopes. Bien.

Decisión: Si ves muchos scopes dispersos, consolida en root para evitar aplicación parcial del tema y problemas de rendimiento.

Tarea 7: Medir regresión del tamaño del bundle de tokens (no publiques un tema como una novela)

cr0x@server:~$ ls -lh dist/tokens.css
-rw-r--r-- 1 cr0x cr0x 34K Feb  4 09:12 dist/tokens.css

Significado de la salida: El tamaño base es modesto.

Decisión: Si salta significativamente, investiga explosión de tokens (frecuentemente por overrides por componente). El tamaño no es solo ancho de banda; es tiempo de parseo.

Tarea 8: Ejecutar una auditoría rápida de contraste en pares críticos (script)

cr0x@server:~$ node scripts/contrast-audit.mjs tokens/theme-dark.json | head
PASS color.text.primary on color.bg ratio=12.8
PASS color.text.secondary on color.bg ratio=7.1
FAIL color.text.disabled on color.surface ratio=2.3
FAIL color.focus.ring on color.bg ratio=2.0

Significado de la salida: Texto deshabilitado y anillo de foco tienen contraste demasiado bajo en sus superficies previstas.

Decisión: Ajustar los valores semánticos (no hacks por componente). Define ratios mínimos por rol (ej., anillo de foco debe ser visible, deshabilitado debe seguir siendo legible cuando sea necesario).

Tarea 9: Detectar “negro/blanco puro” accidental

cr0x@server:~$ rg -n "#000000|#ffffff" tokens/ dist/ packages/ | head
tokens/theme-dark.json:22:    "color.bg": "#000000"
tokens/theme-light.json:18:   "color.text.primary": "#ffffff"

Significado de la salida: Tienes fondo negro puro y texto blanco puro—una receta clásica de deslumbramiento.

Decisión: Reemplazar por casi-negro y off-white, luego volver a chequear contraste y comodidad percibida.

Tarea 10: Ver tokens idénticos entre temas (a menudo señal de trabajo de diseño faltante)

cr0x@server:~$ node scripts/diff-themes.mjs tokens/theme-light.json tokens/theme-dark.json | head
SAME color.link.visited = #6b7cff
SAME color.chart.grid = #2a2f3a
DIFF color.bg light=#ffffff dark=#0f1115

Significado de la salida: Algunos tokens no cambian entre temas. A veces está bien; con frecuencia es mapeo perezoso.

Decisión: Revisa cada token “SAME”. Los links y las cuadrículas de gráficos rara vez se comportan idénticamente en claro y oscuro.

Tarea 11: Verificar comportamiento de prefers-color-scheme en CSS compilado

cr0x@server:~$ rg -n "prefers-color-scheme" dist/app.css
122:@media (prefers-color-scheme: dark) {

Significado de la salida: La app soporta preferencia del SO.

Decisión: Asegura que la preferencia del SO no sobreescriba la selección explícita del usuario. Si lo hace, tu tema “se volteará” y los usuarios abrirán bugs en mayúsculas.

Tarea 12: Comprobar flash de tema incorrecto (FOUC) en HTML renderizado en servidor

cr0x@server:~$ curl -sS -D- http://localhost:3000/ | head -n 30
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
...
<html lang="en">
<head>
...
</head>
<body>

Significado de la salida: Se devuelve HTML, pero no vimos aún el atributo de tema.

Decisión: Si el tema se aplica solo vía JS tardío, tendrás flashes. Arréglalo setando data-theme en el servidor o con un script inline temprano.

Tarea 13: Confirmar que el atributo de tema existe en tiempo de ejecución (chequeo headless)

cr0x@server:~$ node scripts/check-theme-attribute.mjs http://localhost:3000/
OK html[data-theme] present value=dark

Significado de la salida: El tema se aplica lo suficientemente temprano como para ser detectable.

Decisión: Si falta, arregla SSR o bootstrap temprano. No confíes en “se actualiza rápido.” Los usuarios lo notan.

Tarea 14: Encontrar overrides “únicos” de componentes que eluden tokens

cr0x@server:~$ rg -n "background:\s*#|color:\s*#" apps/ packages/ | head
apps/web/src/components/Tag.css:8:  background: #1d2533;
apps/web/src/components/Tag.css:9:  color: #cfe1ff;

Significado de la salida: Existen valores hex codificados en componentes de producto.

Decisión: Reemplazar por tokens semánticos/de componente. Los colores codificados son intratables a escala y derivarán entre temas.

Guía de diagnóstico rápido: encuentra el cuello de botella pronto

Cuando el modo oscuro se ve mal en producción, necesitas una ruta de triage más rápida que una revisión de diseño. Aquí está el orden que encuentra causas raíz con rapidez.

Primero: confirma el selector de tema y el scope

• ¿Está data-theme establecido correctamente en el elemento raíz?
• ¿Las definiciones de variables CSS están scopeadas solo en selectores raíz de tema?
• ¿Hay algún subárbol que esté sobreescribiendo variables?

Si esto está mal, todo lo demás es ruido. Arregla el scope antes de tocar colores.

Segundo: verifica completitud de tokens y fallbacks

• ¿Faltan claves semánticas en el mapeo de modo oscuro?
• ¿Se referencia alguna variable CSS que no está definida?
• ¿Hay fallbacks no intencionados como var(--x, #fff) que se envían a producción?

Los tokens faltantes provocan comportamiento “aleatorio” que cambia entre páginas y componentes. No es aleatorio. Es comportamiento indefinido con mejor branding.

Tercero: identifica el rol que falla, no el componente que falla

• ¿El problema es legibilidad del texto? Entonces inspecciona color.text.*.
• ¿El problema es la jerarquía? Entonces inspecciona tokens de bg/surface/elevation.
• ¿El problema es visibilidad de estados? Entonces inspecciona roles de hover/active/focus/disabled.

Arregla roles a nivel semántico. Parchear un único componente es cómo acumulas deuda de tema.

Cuarto: mide contraste y deslumbramiento contra las superficies previstas

Ejecuta tu auditoría de contraste y revisa los pares que importan. No pierdas tiempo en pares teóricos que nadie usa.

Quinto: revisa síntomas de renderizado y rendimiento

• ¿El toggle de tema causa jank? Sospecha demasiados cambios de estilo por nodo o transiciones.
• ¿Solo algunos componentes se actualizan? Sospecha límites de shadow DOM, iframes, o scopes de tema anidados.
• ¿Los iconos se ven mal? Sospecha pipeline de assets y tokens de fill/stroke en SVG.

Tres mini-historias corporativas (anonimizadas, técnicamente exactas)

Mini-historia #1: Un incidente causado por una suposición equivocada

Una empresa SaaS mediana desplegó modo oscuro en una “semana de plataforma.” Tenían una biblioteca de componentes, un paquete de tokens y un PM confiado.
El plan era simple: mapear los tokens semánticos de modo claro a hex más oscuros, enviar, celebrar.

La suposición equivocada: “Los bordes son solo colores de texto con menor contraste.” En modo claro, habían estado usando un gris ligeramente más oscuro para bordes y
accidentalmente reutilizaron un token de texto porque se veía bien. Llevaron ese atajo al modo oscuro.

En producción, los campos de formulario “desaparecieron” para un subconjunto de usuarios. No todos los usuarios—solo los de paneles de portátiles de gama baja con niveles de negro pobres y
personas con brillo reducido. Los tickets de soporte los describían como “cajas de entrada faltantes”, que sonaba como bugs de layout.

Ingeniería triageó CSS. El layout estaba bien. El DOM estaba bien. Luego alguien activó un overlay de debug que resaltaba elementos focusables: los inputs estaban ahí,
pero el token de borde estaba mapeado a un valor demasiado cercano a la superficie en modo oscuro. El error era sistémico: docenas de componentes dependían de ese rol.

La solución no fue “hacer los bordes más brillantes.” La solución fue introducir separación semántica adecuada: color.border.subtle,
color.border.default, color.text.secondary—y prohibir reutilizar tokens de texto para bordes en revisión de código.
El modo oscuro no rompió su UI. Sus suposiciones lo hicieron.

Mini-historia #2: Una optimización que salió mal

Otra empresa quería conmutación de tema instantánea sin flash y con CSS mínimo. Un ingeniero propuso una optimización ingeniosa:
generar solo un conjunto de variables CSS y “calcular” la paleta oscura en el cliente aplicando una transform al conjunto claro.
Menos tokens, menos CSS, builds más rápidos. Sonaba ordenado.

Lo enviaron detrás de una feature flag. Funcionó… hasta que no. Los colores de marca se volvieron feos porque la transform no preservaba la luminancia percibida.
Colores de advertencia y error se volvieron ambiguos. Los colores de las series en gráficos colisionaron. Los anillos de foco se fundieron con el fondo en algunas superficies.

El dolor operacional fue peor que la estética. Los bugs eran difíciles de reproducir porque la paleta calculada dependía de matemáticas en tiempo de ejecución, redondeos del navegador,
y a veces del zoom del usuario. QA no podía “differ” el tema porque no era un artefacto estático.

La conclusión del postmortem fue directa: optimizaron lo equivocado. El conteo de tokens y el tamaño de CSS no eran su cuello de botella; la corrección y previsibilidad sí lo eran.
Revirtieron a mapeos explícitos por tema con una superficie semántica más pequeña y usaron minificación convencional para tamaño.

El patrón de contraproductividad es común: los trucos “inteligentes” de theming aumentan la complejidad oculta. En sistemas en producción, la complejidad oculta te factura después, con intereses.

Mini-historia #3: Una práctica aburrida pero correcta que salvó el día

Una organización grande corría múltiples productos sobre un design system compartido. Hicieron cumplir una regla que parecía molesta: cada cambio de token requería
actualizar un test snapshot de tokens y un pequeño conjunto de aserciones de contraste. Los ingenieros refunfuñaban; los diseñadores ponían los ojos en blanco.

Luego ocurrió un rebrand. Nuevo color de acento. Nuevos neutrales. Todos esperaban que el tema oscuro fuera un desastre. Los mantenedores de tokens fusionaron los nuevos primitivos,
actualizaron los mapeos semánticos, y CI se iluminó como un dashboard durante un mal despliegue.

Los tests detectaron dos issues inmediatamente: el contraste del anillo de foco bajó por debajo del umbral interno en la superficie más oscura, y el texto deshabilitado quedó demasiado tenue
en un fondo de tabla común. Ninguno era obvio a simple vista, y ambos habrían sido bugs visibles para clientes en pocas horas.

Los arreglaron antes del lanzamiento. El despliegue fue aburrido. Aburrido es el mayor cumplido que puedes dar a un cambio de theming en producción.

La práctica no era glamorosa. Eran solo guardrails: snapshot, checks de contraste y la regla de que el código de producto no puede usar primitivos.
El resultado: el modo oscuro sobrevivió un rebrand con menos incidentes que un refactor CSS menor típico.

Errores comunes: síntoma → causa raíz → solución

1) Síntoma: “Todo se ve gris y plano”

Causa raíz: Los tokens de superficie no codifican elevación; background, surface y superficies elevadas son demasiado similares.

Solución: Define una escala de superficies: bg, surface, surface-2, surface-3 con pasos de luminancia medidos en el tema oscuro. Usa bordes/sombras con moderación y consistencia.

2) Síntoma: “El texto pasa las comprobaciones de contraste pero se siente que brilla”

Causa raíz: Uso de blanco puro o casi blanco sobre casi negro; el alto contraste provoca halation y fatiga ocular.

Solución: Usa off-white para texto primario y sube ligeramente la luminancia del fondo. Mantén contraste suficiente pero no extremo; valida con lectura real, no solo ratios.

3) Síntoma: “Los controles deshabilitados son invisibles”

Causa raíz: Los tokens deshabilitados se derivaron reduciendo opacidad uniformemente; en superficies oscuras esto colapsa distinciones.

Solución: Crea tokens semánticos dedicados para texto deshabilitado, iconos y bordes. Valida sobre la superficie más oscura común y sobre superficies elevadas.

4) Síntoma: “Los anillos de foco desaparecen en algunos componentes”

Causa raíz: El token de anillo de foco no considera los fondos; está demasiado cercano tanto a la superficie como al color de acento.

Solución: Usa un color de anillo de foco con contraste suficiente en ambos bg y surface. Considera anillos dobles (outer + inner) usando dos tokens.

5) Síntoma: “Los bordes se ven demasiado brillantes o pesados”

Causa raíz: Los tokens de borde fueron copiados de la lógica de modo claro o mapeados desde tokens de texto.

Solución: Define roles de borde por separado (subtle, default, strong) y ajústalos por tema. Nunca reutilices tokens de texto para bordes.

6) Síntoma: “El color de marca se ve neón en oscuro”

Causa raíz: El color de acento se usa sin cambios; la saturación y el brillo percibido explotan sobre fondos oscuros.

Solución: Proporciona valores de acento específicos para tema oscuro. Añade tokens semánticos para accent-on-surface y accent-on-accent para texto.

7) Síntoma: “Solo algunas partes de la página cambian de tema”

Causa raíz: Los tokens están scopeados en múltiples lugares o son sobreescritos dentro de estilos de componente; límites de shadow DOM/iframe no manejados.

Solución: Variables a scope raíz. Para iframes/shadow roots, pasa explícitamente el atributo de tema e inyecta variables de forma consistente.

8) Síntoma: “El toggle de tema produce jank”

Causa raíz: El cambio de tema dispara recálculos caros en un DOM grande; transiciones aplicadas ampliamente; estilos inline por componente.

Solución: Mantén variables en root. Reduce transiciones durante cambio de tema. Evita actualizar cientos de nodos; actualiza un atributo.

Listas de verificación / plan paso a paso

Paso a paso: construir un tema oscuro que perdure

1. Define roles semánticos primero. Lista los roles que tu UI necesita: fondos, superficies, niveles de texto, bordes, iconos, estados, foco, overlays, gráficos.
2. Crea una escalera neutral para oscuro. Elige un fondo casi-negro y escala las superficies hacia arriba con diferencias medidas.
3. Establece niveles de texto explícitos. Primario, secundario, terciario, deshabilitado. Usa off-white para primario.
4. Define tokens de estado. Hover/active/focus/disabled para controles comunes, incluyendo variantes sutiles.
5. Mapea semántica a primitivos por tema. No transformes automáticamente; define valores intencionalmente.
6. Genera salidas para plataformas. Variables CSS + JSON + tipos desde una sola fuente.
7. Haz cumplir reglas de consumo. El código de producto no puede referenciar primitivos; solo semántica/componentes.
8. Añade checks en CI. Completitud, duplicados, pruebas de contraste para pares críticos, snapshot del output de tokens.
9. Ejecuta regresión visual en pantallas representativas. Auth, settings, tablas, modales, formularios, estados vacíos, estados de error.
10. Despliega gradualmente. Feature flag, mide tickets de soporte, monitoriza feedback de sesiones y luego expande.

Checklist: “¿Este tema oscuro parece caro?”

• Las superficies muestran jerarquía sin depender de bordes gruesos.
• El texto es legible por sesiones largas; no hay efecto de “brillo”.
• El foco es inconfundible en cada superficie y componente.
• Los estados deshabilitados son claramente deshabilitados, no invisibles.
• Error/advertencia/éxito son distintos y no dolorosamente saturados.
• Los gráficos siguen siendo legibles; cuadrículas y ejes no desaparecen.
• No hay valores hex codificados en el código de producto.
• El cambio de tema es rápido y no muestra el tema incorrecto.

Checklist: gobernanza de tokens que no se convierte en comité

• Un grupo propietario para la fuente de verdad de tokens.
• Criterios claros para añadir un token semántico.
• Proceso de deprecación con advertencias y migraciones.
• Reporte automatizado para fuga de primitivos y tokens sin usar.
• Notas de release para cambios de tokens que impactan semántica UI.

Preguntas frecuentes

1) ¿Debería tener paletas primitivas separadas para claro y oscuro?

Para neutrales: sí, generalmente. Para acentos de marca: a menudo sí. Intentar reutilizar un conjunto primitivo único entre temas tiende a producir neutrales fangosos o acentos neón.
Mantén la semántica estable; permite que los primitivos difieran por tema.

2) ¿Vale la pena la sobrecarga de tokens semánticos?

Si tienes más de un equipo o más de un producto, sí. Los tokens semánticos evitan que cada componente se convierta en su propio experimento de teoría del color.
También hacen que los bugs de tema sean diagnosticables: arreglas un rol, no 40 componentes.

3) ¿Podemos usar solo opacidad para estados deshabilitados?

Puedes, pero es frágil en modo oscuro. El blend por opacidad depende de lo que hay detrás del elemento y puede colapsar contraste de forma impredecible.
Prefiere tokens deshabilitados explícitos para texto/iconos/bordes, validados en superficies comunes.

4) ¿Cuál es el mejor color de fondo para modo oscuro?

Casi-negro con un ligero tinte, elegido junto con tus pasos de superficie. El “mejor” valor es el que soporta jerarquía y lectura prolongada sin deslumbramiento.
Si eliges negro puro, pasarás tiempo compensando en todas partes.

5) ¿Cómo manejamos imágenes e ilustraciones?

Trátalas como assets con variantes de tema o diseña para que funcionen en ambos fondos. Para iconos SVG, prefiere currentColor y tokens semánticos para iconos.
Para ilustraciones, decide si proveer variantes oscuras o mantenerlas en contenedores neutrales.

6) ¿Cómo evitamos un flash del tema incorrecto en la primera carga?

Aplica data-theme antes del primer paint: renderízalo en el servidor cuando sea posible, o ejecuta un pequeño script inline en el head que lea la preferencia almacenada
y establezca el atributo inmediatamente.

7) ¿WCAG garantiza que nuestro modo oscuro sea bueno?

WCAG te ayuda a no enviar texto ilegible. No garantiza comodidad o calidad estética. Usa verificaciones de contraste como guardrails, luego evalúa deslumbramiento, jerarquía
y visibilidad de estados en pantallas reales a brillos realistas.

8) ¿Cómo soportamos múltiples marcas sin forkear todo?

Mantén una capa semántica compartida entre marcas. Proporciona paletas primitivas específicas por marca y mapeos semánticos. Si las marcas necesitan semánticas distintas, cuestiona eso:
a menudo es en realidad una petición de variante de componente, no un nuevo contrato semántico.

9) ¿Deberíamos animar el cambio de tema?

Ligeramente, si acaso. Un desvanecimiento sutil de fondo puede ser agradable; animar cada cambio de token es caro y puede parecer que la UI se está derritiendo.
Prioriza corrección y velocidad; la animación es opcional.

10) ¿Cuál es la regla más simple para aplicar en revisión de código?

“No colores codificados en el código de producto.” Si un color debe existir, debe ser un token con semántica. Esta única regla elimina una gran clase de regresiones.

Siguientes pasos que puedes hacer esta semana

1. Haz inventario de tus tokens semánticos. Escribe el glosario: qué significa cada rol y para qué nunca debe usarse.
2. Ejecuta detección de fuga. Encuentra primitivos y hex codificados en el código de producto; abre una backlog de migración.
3. Añade dos checks de CI inmediatamente: (a) completitud semántica por tema, (b) auditoría de contraste para pares críticos.
4. Arregla los tres mayores causantes de mala percepción: fondo casi-negro + texto off-white + anillo de foco visible en cada superficie.
5. Elige una “pantalla hero” y una “pantalla peor”. Hazlas perfectas en modo oscuro. Luego escala, componente por componente.
6. Deja de hacer trabajo de tema en componentes. El mapeo de tema pertenece a los tokens. Los componentes consumen semántica. Mantén el contrato limpio.

Un modo oscuro que no se ve barato no es una paleta milagrosa. Es un sistema operacionalmente sólido: semántica, capas, pruebas y una negativa a enviar comportamiento indefinido.
Contrúyelo como construyes infraestructura confiable—porque a escala, eso es lo que es.