Tokens de diseño para un tema de documentación: variables CSS, modo oscuro estilo X, movimiento reducido

Qué son realmente los tokens de diseño (y qué no son)

Un token de diseño es una decisión nombrada. No es un color. No es una tipografía. No es “#1d9bf0”.
Una decisión: “este es el color de acento” o “este es el color del anillo de foco” o “este es el espaciado entre párrafos apilados”.
Los tokens te permiten hablar sobre decisiones de forma que sobrevivan a rediseños, modo oscuro y tres frameworks CSS distintos intentando ocupar el mismo repositorio.

Capas de tokens: no te saltes esto o lo lamentarás después

Si lo aplanas todo en un montón de variables, creas un tema que no puede evolucionar. Quieres capas:

• Tokens base: primitivos en crudo como colores (en un espacio perceptual si es posible), familias tipográficas, pasos de espaciado.
• Tokens semánticos: nombres basados en intención como --color-bg, --color-fg, --color-accent.
• Tokens de componente: solo cuando es necesario, p. ej., --codeblock-bg o --sidebar-hover-bg.

Los tokens base pueden cambiar durante un rebranding. Los tokens semánticos deberían permanecer mayormente estables. Los tokens de componente son
una válvula de escape controlada: úsalos con moderación y solo cuando los tokens semánticos no puedan expresar las restricciones de un componente.

Qué no son los tokens

• No son un vertedero para cualquier valor hexadecimal que alguien pegó desde un mock.
• No son un reemplazo para primitivos de layout y un diseño de componentes sensato.
• No son una licencia para inventar nombres divertidos como --blueberry-muffin. No estás manejando una heladería.

Un heurístico confiable: si el nombre de una variable no ayudaría a alguien a depurar un problema de contraste a las 2 a.m., no es un token,
es un secreto.

Hechos y contexto histórico que importan en 2025

Los temas y los tokens parecen una moda. Lo son, pero también son el punto de convergencia de unas décadas de historia del CSS,
trabajo en accesibilidad y convenciones de plataforma. Aquí hay hechos concretos que influyen en los temas de documentación actuales:

1. Propiedades personalizadas de CSS (variables) se implementaron ampliamente alrededor de 2017. Eso es lo suficientemente antiguo para confiar en producción, y lo bastante nuevo para que algunos equipos todavía las eviten por hábito.
2. prefers-color-scheme se volvió utilizable en navegadores modernos alrededor de 2020–2021, convirtiendo el modo oscuro de “archivo CSS extra” a una señal de preferencia de usuario de primera clase.
3. prefers-reduced-motion es una media query nacida de las configuraciones de accesibilidad del sistema operativo; ignorarla equivale a ignorar “me marean las animaciones”. Los usuarios lo notan.
4. La guía de contraste WCAG (notablemente 2.1 y posteriores) empujó a los equipos fuera del “se ve bien en mi portátil” hacia legibilidad medible para texto normal y grande.
5. La adopción de OLED hizo que los fondos negros puros fueran más comunes —pero también hace que el texto muy brillante y los acentos saturados resulten más agresivos. “Modo oscuro” no es “#000 en todas partes”.
6. El resaltado de sintaxis para bloques de código es ahora una superficie central de legibilidad. No es decorativo; es literalmente cómo tus docs comunican. Los malos tokens aquí cargan silenciosamente a los usuarios.
7. Los esfuerzos de estandarización de tokens de diseño (incluyendo formatos comunitarios y toolchains) normalizaron la idea de tokens como artefacto de canalización, no solo variables CSS en un archivo.
8. Las convenciones de interfaz del sistema entrenaron a los usuarios para esperar que la elección de tema se recuerde por sitio, pero que por defecto siga la preferencia del sistema. Si luchas contra esto, pierdes. Silenciosamente, pero pierdes.

Esto no es trivia. Es la razón por la que el enfoque “simplemente elige algunos colores” muere en cuanto tus docs se vuelven populares.

Un modelo de tokens que no colapsará después

Los temas de documentación tienen un problema especial: son mayormente tipografía y densidad de contenido, con pequeños elementos interactivos
(navegación, búsqueda, botones de copiar código). Eso tienta a los equipos a subdiseñar los tokens. Luego llega la primera solicitud de cambio “menor”:
nuevos tipos de callout, badges de métodos API, un tema de sintaxis diferente—y de repente estás depurando por qué #fff se usa 46 veces en 12 archivos.

Comienza con restricciones: los docs no son un sitio de marketing

Tu tema de docs debería optimizar para:

• Legibilidad en sesiones largas.
• Consistencia entre tipos de contenido (Markdown, tablas, código, diagramas).
• Interacción predecible (estados de foco, hover, navegación por teclado).
• Bajo riesgo de regresión cuando cambias tokens.

Tu tema de docs no debería optimizar para:

• Máxima saturación de marca en cada píxel.
• Animaciones novedosas.
• “Encantamiento” que rompe el desplazamiento o desencadena sensibilidad al movimiento.

Nomenclatura de tokens con criterio

Usa un esquema de nombres que codifique intención y escala. Por ejemplo:

• --space-1, --space-2, --space-3… para pasos de espaciado (tokens base).
• --radius-1, --radius-2… para radios de esquina.
• --color-neutral-0… --color-neutral-100 para la escala neutral (tokens base).
• --color-bg, --color-fg, --color-muted, --color-border (tokens semánticos).
• --color-link, --color-link-hover, --color-focus-ring (tokens semánticos, aún basados en intención).

Evita vincular tokens semánticos a nombres de marca: --color-twitter-blue es un futuro reporte de bug.
La marca cambiará o el contexto cambiará, y el nombre de tu token mentirá.

Cantidad de tokens: menos de lo que piensas, más de lo que quieres

Si defines 300 tokens en el día uno, no estás construyendo un tema—estás construyendo un segundo trabajo.
Si defines 12 tokens, estás construyendo una trampa.

Un punto de partida práctico para un tema de docs:

• Rampa de neutrales: 10–14 pasos.
• Acento + estados: acento, acento-hover, acento-suave, anillo de foco.
• Colores de estado: success/warn/error/info con dos pasos cada uno (sólido + fondo sutil).
• Tipografía: 2 familias (ui + mono), 1–2 tokens de altura de línea, pasos de escala para tamaño de fuente.
• Espaciado + radios: 6–8 pasos cada uno.

Eso es suficiente para tematizar todo el sitio sin convertir tu CSS en una danza interpretativa.

Variables CSS en producción: mecánica y bordes afilados

Las propiedades personalizadas de CSS son variables resueltas en tiempo de ejecución. Esa es la característica y la trampa.
Heredan, pueden sobreescribirse y participan en la cascade. Esto las hace perfectas para temas.

Usa la cascada a propósito

La cascada no es caos. Es un plano de control. Tu sitio de docs debería definir tokens en:

• :root para valores por defecto.
• [data-theme="dark"] para sobrescrituras de modo oscuro.
• Opcional: ámbitos de componente como .codeblock solo para tokens de componente.

No definas tokens en niveles anidados al azar a menos que estés intencionalmente scopeándolos. De lo contrario obtendrás bugs de “funciona en una página”
porque un contenedor cambió un token y el componente hijo lo heredó.

Prefiere tokens semánticos para el estilo de componentes

Un componente debería referirse mayormente a tokens semánticos. Ejemplo:
El bloque de código debería usar --color-bg-elevated y --color-fg, no --color-neutral-95.
Si codificas pasos de la rampa base en los componentes, no podrás reajustar el contraste después sin tocar el CSS del componente.

Rendimiento: las variables no son tu cuello de botella hasta que lo son

La mayoría de los temas no alcanzan límites de rendimiento por las variables por sí solas. Pero puedes crear problemas:

• Animar una variable que afecta layout o propiedades de pintura pesadas en toda la página.
• Usar en exceso filter, backdrop-filter o sombras grandes mientras se alternan temas.
• Provocar restyles costosos al cambiar el tema en la raíz por cada interacción pequeña.

Mantén los cambios de tema poco frecuentes (acción del usuario, no hover). Mantén las transiciones sutiles y acotadas.

Una cita que vale la pena recordar

“La esperanza no es una estrategia.” — General Gordon R. Sullivan

La corrección del tema no es una actividad basada en sensaciones. Mide el contraste, prueba la reducción de movimiento y ejecuta cheques de regresión.

Modo oscuro “como X”: alto contraste, baja dramatización, no negro absoluto

La gente dice “modo oscuro como X” porque es legible, nítido y no parece una cabina de ciencia ficción.
Tiende a usar un fondo casi negro (no negro puro), superficies ligeramente elevadas y texto brillante pero controlado.
La clave es la rampa neutral y cómo la asignas a las superficies.

Por qué el casi-negro vence al negro puro para docs

El negro puro (#000) maximiza el contraste, lo cual suena bien hasta que lees durante 40 minutos. Muchos usuarios reportan
halación (bordes brillantes) con texto claro sobre negro puro. El casi-negro reduce el deslumbramiento mientras sigue sintiéndose “oscuro”.

Además: no todos los displays se comportan igual. Algunas pantallas aplastan sombras, algunos teléfonos aumentan el contraste y algunos navegadores
aplican gestión de color de forma distinta. El casi-negro te da margen para crear elevación y bordes sin depender de valores invisibles.

Define superficies: base, elevada, insertada

Los temas de docs necesitan tokens de superficie. Si solo tienes un token de fondo, terminarás inventando grises ad-hoc.
Usa un conjunto pequeño de superficies:

• --color-bg para la base de la página.
• --color-bg-elevated para navegación, paneles, tarjetas.
• --color-bg-inset para bloques de código, callouts y contenedores insertados.

Haz que los bordes sean reales en modo oscuro

En modo claro puedes ahorrar con bordes sutiles. En modo oscuro, los bordes o desaparecen o se vuelven contornos neón.
Tokeniza los bordes con intención:

• --color-border para trazos por defecto.
• --color-border-strong para separadores y líneas de rejilla de tablas.

Si usas un solo color de borde, las tablas y las barras laterales se difuminarán hasta volverse fango, especialmente para usuarios con percepción de bajo contraste.

Enlaces y acentos: el modo de fallo “demasiado azul”

Los temas estilo X usan un acento saturado, pero controlan dónde aparece. Tus docs deberían hacer lo mismo:

• Enlaces: color de acento, pero evita subrayados demasiado finos en fondos oscuros.
• Botones: fondo de acento con texto legible, pero mantén los estados hover dentro de un delta pequeño.
• Anillos de foco: no reutilices el acento a ciegas; elige un color de anillo visible en superficies claras y oscuras.

Broma #1: El modo oscuro no es “hacer todo negro”. Eso no es tematizar; es un corte de energía con tipografía.

Resaltado de sintaxis: no dejes que se aproveche gratis

Los bloques de código son donde la mayoría de los temas oscuros fallan en silencio. El fondo es oscuro, luego los tokens usan colores saturados que
vibran, y los ojos del usuario se declaran en huelga. Tokeniza los colores de sintaxis por separado y mantenlos dentro de una paleta controlada.

Regla práctica: mantiene los colores de sintaxis menos saturados que el acento, y asegúrate de que los comentarios sean legibles pero no dominantes.
Si el color de los comentarios es demasiado tenue, la gente no distinguirá código de anotación; si es demasiado brillante, se vuelve ruido visual.

Movimiento reducido: el contrato que ya estás violando

La reducción de movimiento no es “agradable de tener”. Es una preferencia explícita del usuario. Cuando un usuario activa la reducción de movimiento,
te está diciendo que la animación puede causar incomodidad o náuseas. Si tu sitio de docs todavía desplaza suavemente, hace cross-fades, parallax,
o anima transformaciones grandes, estás violando el contrato.

Qué deshabilitar (y qué mantener)

Bajo prefers-reduced-motion: reduce:

• Deshabilita desplazamiento suave, efectos parallax, carruseles auto-rotativos, gradientes de fondo animados.
• Reduce grandes transiciones de transformaciones (aperturas de sidebar), fades largos y realces animados.
• Mantén micro-transiciones cortas y no esenciales si no generan movimiento visible en el viewport (p. ej., cambios de color de 100ms). Pero considera deshabilitarlas también por simplicidad.

El comportamiento de desplazamiento es la trampa clásica

Muchos sitios de docs ponen html { scroll-behavior: smooth; } porque “se ve refinado.”
Bajo reducción de movimiento, es lo opuesto a refinado.
Tu arquitectura de tokens y CSS debería permitir apagarlo limpiamente.

Tokens de animación: sí, vale la pena tokenizar el movimiento

Crea tokens de movimiento:

• --motion-duration-fast, --motion-duration-medium
• --motion-ease-standard
• --motion-enabled como interruptor conceptual (implementado vía sobrescrituras de media query)

Luego, bajo reducción de movimiento, establece las duraciones casi a cero. No confíes en auditar cada línea de transition manualmente.
Te faltará una. Siempre te falta una.

Plano de implementación: tokens, capas y sobrescrituras

Estructura CSS: separa tokens del CSS de componentes

Coloca los tokens en un solo archivo (o en un bundle generado) que se cargue temprano. Luego construye componentes que consuman tokens.
El anti-patrón es mezclar tokens dentro de archivos de componentes, porque hace que la superficie de tokens sea inrevisable.

Un diseño práctico de tokens

Archivos recomendados:

• tokens.css: tokens base + semánticos, claro y oscuro.
• components.css: componentes que referencian tokens semánticos.
• overrides.css: correcciones raras por página o por integración; trata esto como radioactivo.

Contrato de cambio de tema

Soporta estos modos:

• Sistema (por defecto): sigue prefers-color-scheme.
• Claro (anulación del usuario): forzar claro independientemente del sistema.
• Oscuro (anulación del usuario): forzar oscuro independientemente del sistema.

Implementa con un atributo data-theme en html o body, más un estado “sistema” donde el atributo está ausente.
No uses simultáneamente atributo y clases de diferentes frameworks; crearás selectores en conflicto y pasarás una tarde perdiendo contra la especificidad.

Contrato de reducción de movimiento

Usa media queries, no hacks del agente de usuario:

• @media (prefers-reduced-motion: reduce) { ... }

Evita usar JS para “detectar” reducción de movimiento a menos que sea absolutamente necesario. CSS es más confiable y no depende del tiempo de ejecución de scripts.

Ejemplo: archivo de tokens (conceptual)

No te voy a ahogar en un volcado completo de CSS de tema, pero aquí está el patrón: rampas base, luego mapeo semántico, luego sobrescrituras para oscuro.
Mantén tus tokens ajustados y legibles.

Herramientas y canalizaciones: mantén a los humanos fuera del camino crítico

El theming en producción es como el almacenamiento en producción: tus fallos suelen ser mundanos y autoinfligidos. Las herramientas ayudan, pero solo
si las tratas como barandillas y no como varita mágica.

Linting y cheques de consistencia

Usa un linter de estilos para detectar:

• Colores hard-coded en CSS de componentes (cuando requieres tokens).
• Referencias inválidas de variables.
• Selectores excesivamente específicos que hacen imposibles las sobrescrituras de tokens.

Pruebas de contraste como señal de build

No publiques un cambio de tema sin revisar contraste para:

• Texto del cuerpo sobre el fondo
• Enlaces sobre el fondo
• Texto de código sobre fondo de código
• Texto atenuado y colores de borde (a menudo los primeros en fallar en modo oscuro)

No necesitas perfección. Necesitas una política consistente y una forma de bloquear regresiones obvias.

Pruebas de regresión visual: seguro barato

Para sitios de docs, la regresión visual es desproporcionadamente efectiva porque las páginas están templadas.
Captura un pequeño conjunto de páginas canónicas:

• Página principal / landing
• Página de referencia de API con tablas
• Página de tutorial con callouts
• Vista de resultados de búsqueda
• Página con bloques de código largos

Ejecútalas en claro y oscuro, y con reducción de movimiento. Sí, la reducción de movimiento afecta capturas si tienes animaciones que pueden capturarse a mitad de transición.
Ese es el punto: capturar nondeterminismo.

Dos chistes sobre temas es la dosis máxima segura

Broma #2: Si crees que no necesitas tokens, nunca conociste “solo este azul especial” en un rebranding trimestral.

Tareas prácticas: comandos, salidas y decisiones (12+)

Estas son las comprobaciones que ejecutas cuando un cambio de tema está a punto de publicarse, o cuando algo se siente “mal” y quieres
encontrar la causa real. Cada tarea incluye: el comando, qué significa la salida y la decisión que tomas.
Asume un repo con un sitio compilado en dist/ y CSS fuente en src/.

Task 1: Find hard-coded hex colors that bypass tokens

cr0x@server:~$ rg -n --hidden --glob '!dist/**' -e '#[0-9a-fA-F]{3,8}\b' src
src/components/sidebar.css:42:  border-left: 1px solid #2f3336;
src/pages/api.css:118:          color: #1d9bf0;

Output meaning: You have literal colors in component/page CSS.
Decision: Replace with semantic tokens (e.g., --color-border, --color-link) or justify why a component token is required.

Task 2: Find rgb()/hsl() literals (also bypass tokens)

cr0x@server:~$ rg -n --hidden --glob '!dist/**' -e '\brgb(a)?\(' -e '\bhsl(a)?\(' src
src/components/callout.css:9:  background: rgba(29, 155, 240, 0.12);

Output meaning: Color math is embedded in components.
Decision: Move the computed values into tokens (e.g., --color-accent-subtle-bg) so dark mode can override correctly.

Task 3: Enumerate CSS variables defined in tokens

cr0x@server:~$ rg -n '^\s*--[a-z0-9-]+\s*:' src/tokens.css | head
12:  --space-1: 0.25rem;
13:  --space-2: 0.5rem;
14:  --radius-1: 6px;
15:  --color-bg: #ffffff;
16:  --color-fg: #0f1419;

Output meaning: A quick view of token definitions.
Decision: Confirm naming consistency and that semantic tokens exist for every major UI surface (bg/fg/border/link/focus).

Task 4: Detect variables used but never defined (typos and dead tokens)

cr0x@server:~$ python3 - <<'PY'
import re, pathlib
root = pathlib.Path("src")
defs=set()
uses=set()
for p in root.rglob("*.css"):
    t=p.read_text(errors="ignore")
    for m in re.finditer(r'--[a-z0-9-]+(?=\s*:)', t): defs.add(m.group(0))
    for m in re.finditer(r'var\(\s*(--[a-z0-9-]+)', t): uses.add(m.group(1))
missing=sorted(uses-defs)
print("\n".join(missing[:50]))
print(f"\nmissing_count={len(missing)}")
PY
--color-codblock-bg
--motion-duration-fst

missing_count=2

Output meaning: Tokens referenced in CSS are not defined; these are likely typos.
Decision: Fix the spelling, or define the token intentionally. This is a classic source of “works in light mode but not dark mode” regressions.

Task 5: Find where data-theme is applied in built HTML

cr0x@server:~$ rg -n 'data-theme=' dist/**/*.html | head
dist/index.html:2:<html lang="en" data-theme="dark">

Output meaning: Your build is hardcoding a theme.
Decision: Decide if that’s intentional (e.g., docs preview) or a bug. Most production sites should default to system preference unless a user setting is stored.

Task 6: Verify that reduced motion rules exist

cr0x@server:~$ rg -n 'prefers-reduced-motion' src/**/*.css
src/tokens.css:148:@media (prefers-reduced-motion: reduce) {
src/components/search.css:77:@media (prefers-reduced-motion: reduce) {

Output meaning: You have explicit reduced-motion handling.
Decision: Ensure it actually disables smooth scrolling and major transitions (not just “duration: 0” in one component).

Task 7: Detect global smooth scrolling (often wrong for reduced motion)

cr0x@server:~$ rg -n 'scroll-behavior\s*:\s*smooth' src/**/*.css
src/base.css:3:html { scroll-behavior: smooth; }

Output meaning: Global smooth scrolling is enabled.
Decision: Add a reduced-motion override: under prefers-reduced-motion: reduce, set scroll-behavior: auto.

Task 8: Check for “transition: all” (a performance and accessibility smell)

cr0x@server:~$ rg -n 'transition\s*:\s*all\b' src/**/*.css
src/components/tabs.css:21:  transition: all 250ms ease;

Output meaning: You are animating everything, including properties that cause layout/paint churn.
Decision: Replace with explicit properties (e.g., color, background-color, opacity) and shorten duration; disable under reduced motion.

Task 9: Check CSS bundle size and growth over time

cr0x@server:~$ ls -lh dist/assets/*.css
-rw-r--r-- 1 cr0x cr0x 184K Dec 29 10:11 dist/assets/site.css
-rw-r--r-- 1 cr0x cr0x  62K Dec 29 10:11 dist/assets/vendor.css

Output meaning: Bundle sizes are visible and measurable.
Decision: If your site CSS is ballooning release-to-release, suspect “token bypass” and component duplication. Decide whether to dedupe, split, or enforce token usage.

Task 10: Inspect computed values in a headless browser (dark vs light)

cr0x@server:~$ node - <<'NODE'
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('file://' + process.cwd() + '/dist/index.html');
  const bg = await page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--color-bg').trim());
  const fg = await page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--color-fg').trim());
  console.log({bg, fg});
  await browser.close();
})();
NODE
{ bg: '#0b0f14', fg: '#e7e9ea' }

Output meaning: Tokens resolve to actual values at runtime.
Decision: Compare outputs for light and dark, and verify that semantic tokens change while component CSS stays stable.

Task 11: Confirm the site respects system color scheme without forcing

cr0x@server:~$ node - <<'NODE'
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage({ colorScheme: 'dark' });
  await page.goto('file://' + process.cwd() + '/dist/index.html');
  const attr = await page.evaluate(() => document.documentElement.getAttribute('data-theme'));
  const bg = await page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--color-bg').trim());
  console.log({dataTheme: attr, bg});
  await browser.close();
})();
NODE
{ dataTheme: null, bg: '#0b0f14' }

Output meaning: The page is following system preference (dark) without an explicit override attribute.
Decision: Keep this behavior unless product requirements demand a forced default. “System by default” reduces user friction.

Task 12: Find “!important” usage that can break token overrides

cr0x@server:~$ rg -n '!\s*important' src/**/*.css
src/components/navbar.css:55:  background: var(--color-bg-elevated) !important;

Output meaning: Specificity escalation is present.
Decision: Remove !important unless you’re deliberately fighting third-party CSS. If you must keep it, isolate it in an integration layer so core theme tokens remain overrideable.

Task 13: Validate that the reduced-motion override actually changes computed transition duration

cr0x@server:~$ node - <<'NODE'
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage({ reducedMotion: 'reduce' });
  await page.goto('file://' + process.cwd() + '/dist/index.html');
  const dur = await page.evaluate(() => getComputedStyle(document.documentElement).getPropertyValue('--motion-duration-medium').trim());
  console.log({motionDurationMedium: dur});
  await browser.close();
})();
NODE
{ motionDurationMedium: '1ms' }

Output meaning: Your motion tokens are being overridden for reduced motion.
Decision: If this stays at something like 250ms, your reduced-motion CSS is missing or not loading early enough.

Task 14: Check for layout shift caused by font loading (docs sites are sensitive)

cr0x@server:~$ rg -n 'font-display' src/**/*.css src/**/*.scss
src/fonts.css:4:  font-display: swap;

Output meaning: Fonts are configured to swap, reducing “invisible text” time but potentially causing minor shift.
Decision: For docs, swap is usually the right choice; if you see ugly shifts, adjust fallback font metrics or consider optional depending on UX goals.

Guía rápida de diagnóstico

Cuando un tema de docs “se siente mal”, el truco es evitar debatir sobre gustos y en su lugar aislar el cuello de botella: contraste,
mapeo de tokens, comportamiento de movimiento o conflictos de cascada. Aquí está el orden que te lleva a respuestas rápido.

Primero: verifica el estado del tema y la cascada

• ¿El sitio sigue la preferencia del sistema o fuerza un tema vía data-theme?
• ¿Se cargan los archivos de tokens antes que el CSS de componentes?
• ¿Hay reglas !important o resets de framework que estén sobreescribiendo tokens?

Por qué primero: Si la cascada está mal, todo lo demás es ruido. No puedes depurar contraste si se aplica el tema equivocado.

Segundo: valida que los tokens semánticos resuelvan valores sensatos

• Revisa computados --color-bg, --color-fg, --color-link, --color-border.
• Confirma que el modo oscuro cambia los tokens semánticos, no el CSS del componente.

Por qué segundo: Los tokens semánticos son tu contrato. Si son inconsistentes, los componentes nunca serán consistentes.

Tercero: señales de accesibilidad—reducción de movimiento y contraste

• Bajo reducción de movimiento: ¿se deshabilita el desplazamiento suave y las transiciones principales están casi a cero?
• ¿El foco es visible en la navegación por teclado en ambos temas?
• Revisa contraste en texto del cuerpo, enlaces, bloques de código, callouts y tablas.

Por qué tercero: Estos son fallos que impactan al usuario y que pueden persistir inadvertidos durante meses. No siempre aparecen en pruebas de camino feliz.

Cuarto: rendimiento y determinismo

• Busca transition: all, sombras grandes, filtros y propiedades animadas que afecten el layout.
• Confirma que los snapshots de regresión visual son estables (sin capturas a mitad de transición).

Por qué cuarto: Los problemas de rendimiento del tema suelen ser autoinfligidos y obvios una vez que sabes dónde mirar.

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

1) “El modo oscuro se ve lavado, pero solo en algunas páginas”

Síntoma: La mayoría de las páginas se ven bien; unas pocas tienen texto gris sobre gris o callouts ilegibles.
Causa raíz: Contenedores anidados sobrescriben un token semántico (p. ej., --color-fg) o un componente usa directamente tokens de la rampa base.
Solución: Restringe las sobrescrituras de tokens a selectores root del tema; refactoriza componentes para que usen solo tokens semánticos.

2) “Los enlaces son invisibles en modo oscuro”

Síntoma: Los enlaces parecen texto del cuerpo a menos que se haga hover.
Causa raíz: El token de enlace está demasiado cercano al token de primer plano; el token de hover depende de aumentar brillo que no funciona en fondos casi negros.
Solución: Incrementa la separación de matiz y/o añade mayor grosor al subrayado; define --color-link y --color-link-hover explícitamente por tema.

3) “El anillo de foco desaparece en bloques de código y botones”

Síntoma: Usuarios de teclado no ven el foco en algunos componentes.
Causa raíz: El color del anillo de foco reutiliza el acento que se funde con los fondos; o los estilos de foco usan outline: none sin reemplazo.
Solución: Crea --color-focus-ring con alta visibilidad en ambos temas; prohíbe outline: none a menos que se añada un contorno mejor.

4) “El cambio de tema provoca un flash o parpadeo”

Síntoma: Cambiar el tema provoca un flash de blanco o una paleta en estado intermedio.
Causa raíz: El archivo de tokens carga tarde, o JS aplica data-theme después del primer pintado.
Solución: Inlinea un script mínimo de inicialización de tema en el head del documento (o evita forzar tema por defecto); asegúrate de que el CSS de tokens se cargue en la ruta crítica.

5) “La reducción de movimiento está activada pero el desplazamiento aún se anima”

Síntoma: El usuario reporta molestia por movimiento; el dev dice “soportamos reducción de movimiento”.
Causa raíz: scroll-behavior: smooth global no está sobrescrito bajo reducción de movimiento; una librería JS de smooth-scroll ignora la preferencia.
Solución: Añade @media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }; condiciona animaciones JS según la preferencia.

6) “Las tablas son ilegibles en modo oscuro”

Síntoma: Las líneas de la rejilla desaparecen; los fondos alternados de filas no difieren suficiente.
Causa raíz: Un único token de borde usado en todas partes; el striping de filas usa overlays alpha que colapsan en fondos casi negros.
Solución: Añade --color-border-strong y tokens explícitos de fondo de fila por tema.

7) “Los bloques de código parecen una discoteca”

Síntoma: Los colores de sintaxis son dolorosamente saturados, los comentarios son demasiado tenues o el color de selección es ilegible.
Causa raíz: La paleta de sintaxis no está tokenizada; fue copiada desde un fondo distinto; el color de selección quedó por defecto del navegador.
Solución: Define tokens de sintaxis (--syntax-keyword, --syntax-string, etc.) y tokens de selección; valida contraste con el fondo de código.

8) “Ahora todo es un token y nadie puede cambiar nada”

Síntoma: Los ingenieros se quejan de que cambiar un componente requiere editar archivos de tokens y esperar revisión de diseño.
Causa raíz: Los tokens incluyen detalles de layout específicos de componentes y micro-decisiones; la capa semántica está hinchada.
Solución: Empuja detalles de componente de vuelta al CSS de componente; mantiene tokens para decisiones transversales (colores, tipografía, escala de espaciado, escala de movimiento).

Tres microhistorias corporativas desde las trincheras del theming

Incidente: una suposición incorrecta sobre “modo oscuro del sistema”

Una empresa mediana lanzó un portal de docs renovado. El equipo tenía un toggle de tema, un archivo de tokens limpio y un comportamiento
“por defecto del sistema”. Se veía bien en staging. Se publicó un martes porque ese es el día en que todos se sienten valientes.

En pocas horas, comenzaron a llegar tickets de soporte: “Los docs parpadean en blanco cuando los abro.” La primera suposición del equipo
fue problemas de cache. Segunda suposición: la CDN. Tercera suposición: “los usuarios deben estar exagerando.” Esa suposición no envejeció bien.

La causa raíz fue una suposición incorrecta: asumieron que prefers-color-scheme siempre estaría disponible y estable en el primer pintado.
Pero su implementación forzaba un tema vía JS después de la carga para aplicar la preferencia guardada. Si el script cargaba tarde (dispositivo lento,
cadena de scripts de terceros bloqueada, proxy corporativo estricto), la página se renderizaba en modo claro primero y luego cambiaba a oscuro. Flash. Dolor.

Arreglarlo no fue glamoroso. Inlinearon un script mínimo de inicialización de tema en el head del documento para establecer data-theme
antes de la evaluación del CSS, y hicieron que el modo “sistema” por defecto no requiriera JS en absoluto. Resultado: sin flash, menos tickets y un equipo
que dejó de tratar al CSS como “magia frontend”.

Optimización que salió mal: matemática de tokens por todas partes

Otra organización intentó ser lista: querían un único token de color de acento y computar todo lo demás a partir de él usando
CSS color-mix() y overlays alpha. En teoría: menos tokens, más consistencia, rebrands más fáciles.
En la práctica: un descarrilamiento a cámara lenta por diferencias entre navegadores y fondos sutiles ilegibles.

El primer problema fue la predictibilidad. Diferentes navegadores y espacios de color producían resultados ligeramente distintos. En un
fondo oscuro, un overlay de acento al 12% se veía bien en un navegador, lodoso en otro y casi invisible en modos de alto contraste.
El segundo problema fue el control. Cuando diseño quería fondos de callout más calmados en modo oscuro, el equipo tuvo que retocar la matemática,
lo que cambiaba todo lo demás también.

El sistema también se volvió difícil de depurar. Cuando alguien preguntaba “¿qué color es este fondo?”, la respuesta era “depende.”
Esa es una respuesta divertida para un taller de diseño y terrible para una rotación de on-call.

Eventualmente volvieron a tokens semánticos explícitos para superficies y estados clave, manteniendo colores computados solo donde eran seguros y no críticos.
El conteo de tokens subió. Los incidentes bajaron. Es un trade-off que se toma cada vez.

Práctica aburrida pero correcta que salvó el día: páginas canónicas y diff visual

Una tercera compañía mantenía un sitio de docs con múltiples líneas de producto. El tema tenía que soportar tablas largas, diagramas embebidos
y ejemplos de código en tres lenguajes. No eran especiales. Eran disciplinados.

Mantuvieron un pequeño conjunto de páginas canónicas en el repo: una página por cada patrón de contenido desagradable. Cada cambio de tema
ejecutaba diffs de screenshots en claro, oscuro y reducción de movimiento. Si un diff era sorprendente, no se publicaba hasta que alguien
lo explicara en lenguaje claro.

Un día, un cambio aparentemente inocuo actualizó la rampa neutral para hacer el modo oscuro “un poco más oscuro.” El diff señaló que
los bordes de las tablas casi desaparecían y el fondo del código en línea se fusionaba con el fondo del párrafo. Nadie lo notó mirando una sola página,
porque la mayoría de las páginas no tenían tablas densas o código en línea.

Gracias al diff, lo detectaron antes de release y la reparación fue trivial: ajustar dos tokens semánticos y añadir un token de borde más fuerte.
Sin incidentes. Sin hotfix. Sin hilo de emergencia en Slack. Solo una PR normal y todos a casa a tiempo.

Listas de verificación / plan paso a paso

Paso a paso: construir un tema de docs tokenizado desde cero

1. Define superficies y roles de texto: bg, bg elevado, bg insertado, fg, fg atenuado, border, border fuerte.
2. Elige una rampa neutral con suficientes pasos para soportar elevación y bordes sin recurrir a hacks de alpha.
3. Define tokens semánticos para enlaces, anillo de foco, selección y superficies de código.
4. Define tokens de movimiento (duraciones + easing) y configura sobrescrituras para reducción de movimiento.
5. Implementa cambio de tema con predeterminado de sistema y anulación de usuario vía data-theme.
6. Refactoriza componentes para consumir solo tokens semánticos; permite tokens de componente solo por restricciones reales.
7. Añade guardarraíles: linter para colores crudos, localizar tokens indefinidos, prohibir transition: all.
8. Añade snapshots de páginas canónicas en claro/oscuro/reducción de movimiento.
9. Publica y observa: vigila tickets de soporte por contraste, foco y quejas de movimiento; son señal, no ruido.

Checklist de release: antes de fusionar un cambio de tema

• No hay literales de color crudos introducidos fuera de archivos de tokens (o justificados explícitamente).
• Tokens semánticos actualizados para modos claro y oscuro.
• Foco visible en todos los elementos interactivos en ambos temas.
• Modo de reducción de movimiento deshabilita desplazamiento suave y transiciones principales.
• Bloques de código legibles: fondo, selección, comentarios y código inline probados.
• Tablas: bordes y rayado tipo cebra siguen visibles en modo oscuro.
• Diffs de regresión visual revisados en páginas canónicas.
• El cambio de tema no produce flash en el primer pintado.

Checklist de operaciones: diagnosticar una queja de tema en producción

• Reproducir con la configuración reportada por el usuario (modo oscuro, reducción de movimiento, alto contraste si aplica).
• Comprobar si un atributo de tema forzado se aplica tarde por JS (timing de red, scripts bloqueados, problemas CSP).
• Inspeccionar valores semánticos computados en la página afectada.
• Buscar sobrescrituras locales y reglas !important cerca del componente con fallo.
• Comparar contra páginas canónicas para ver si el problema es sistémico o específico del contenido.

Preguntas frecuentes

1) ¿Debo almacenar tokens en variables CSS o generarlos desde una herramienta de diseño?

Almacena el contrato de runtime como variables CSS. Puedes generar ese archivo desde una herramienta si quieres, pero conserva una
salida de tokens legible por humanos. Cuando producción se rompe, quieres depurar en el navegador, no en una canalización de exportación.

2) ¿Qué tan cerca debe estar “modo oscuro como X” del negro puro?

Usa casi-negro para el fondo base, no negro puro. El negro puro puede ser agresivo para la lectura y dificulta la elevación sutil.
El casi-negro te da margen para superficies y bordes sin contornos neón.

3) ¿Está bien usar overlays alpha para fondos sutiles?

A veces. Los overlays alpha son frágiles entre fondos y pueden colapsar en modo oscuro. Prefiere tokens semánticos explícitos
para superficies críticas (callouts, bloques de código). Usa alpha para decoración no crítica y pruébalo en ambos temas.

4) ¿Necesito tokens separados para bloques de código?

Sí, por lo general. Los bloques de código tienen restricciones distintas: contenido denso, colores de sintaxis, estilo de selección y botones de copia.
Trátalos como una superficie con fondo, borde y tokens de sintaxis explícitos.

5) ¿Cuál es la implementación más simple de toggle de tema que no produzca flash?

Por defecto usa la preferencia del sistema vía media query CSS. Solo aplica data-theme cuando el usuario elige explícitamente
claro u oscuro. Si debes aplicarlo en la carga, hazlo antes del primer pintado con un script inline pequeño en el head del documento.

6) ¿Cómo soporto reducción de movimiento sin reescribir todo el CSS?

Tokeniza duraciones de movimiento y referencia esos tokens en las transiciones. Bajo prefers-reduced-motion: reduce, sobrescribe
los tokens de duración a casi cero y deshabilita desplazamiento suave. Esto cubre la mayoría del movimiento sin buscar cada línea de transición.

7) ¿Por qué no usar simplemente el tema de un framework UI y listo?

Los temas de frameworks están bien hasta que tu sitio de docs tiene bloques de código, tablas, callouts y componentes específicos de contenido
que no estaban en el camino feliz del framework. Los tokens te permiten adaptar sin forkear todo el CSS del framework o luchar con la especificidad para siempre.

8) ¿Cuántos tokens son “demasiados”?

Cuando no puedes responder “para qué sirve este token” sin abrir Figma, tienes demasiados. Los tokens deben codificar decisiones estables.
Si un token existe solo para hacer un componente ligeramente distinto, probablemente sea CSS de componente, no un token.

9) ¿Los tokens ayudan con la fiabilidad o es solo higiene de diseño?

Ayudan a la fiabilidad porque reducen el radio de cambio. Un ajuste de token semántico puede arreglar contraste en todo el sitio sin tocar CSS de componentes,
y las pruebas de regresión pueden centrarse en la capa de tokens. Eso son menos casos raros y extraños en producción.

Conclusión: siguientes pasos que no te harán perder la semana

Construye el tema como si gestionaras producción: define contratos, reduce lo desconocido y mantiene el radio de cambio pequeño.
Los tokens de diseño son ese contrato. Las variables CSS son el mecanismo en tiempo de ejecución. El modo oscuro y la reducción de movimiento
no son “features”—son expectativas de usuario que cumples o no.

Pasos prácticos:

1. Audita tu CSS en busca de colores crudos y transition: all; mueve decisiones a tokens semánticos.
2. Implementa modo oscuro por defecto del sistema con anulación explícita del usuario vía data-theme.
3. Añade tokens de movimiento y una sobrescritura estricta para reducción de movimiento (incluyendo desplazamiento suave).
4. Crea 5–8 páginas canónicas y ejecuta diffs visuales en claro/oscuro/reducción de movimiento antes de fusionar cambios de tema.
5. Haz que bordes, tablas, bloques de código, anillos de foco y estilo de selección sean tokens de primera clase. Ahí es donde los temas realmente fallan.

Si haces esto bien, nadie elogiará tu tema de docs. Simplemente leerán. Esa es la victoria.