Cómo Crear el Modo Oscuro en Figma con Variables

El modo oscuro en Figma funciona vinculando los rellenos de los componentes a Variables semánticas que resuelven diferentes valores de color por Modo - cambia el Modo en cualquier frame y cada componente vinculado se actualiza al instante, sin intercambio manual de rellenos. La forma fiable de construirlo es una arquitectura de dos colecciones: una colección Primitivas para valores de color en bruto y una colección Semántica con modos Claro y Oscuro que alias esas Primitivas. Este artículo cubre esa configuración de principio a fin: estructura de colecciones, convenciones de nomenclatura, exportación CSS y cambio de tema en el navegador.

Flujos relacionados: Design Tokens de Figma: La Guia Completa para los fundamentos de tokens, Auditoria de Contraste WCAG en Figma para validar la accesibilidad de tus temas, y Paridad Figma-Codigo para sincronizar los tokens de modo oscuro con tu repositorio.

¿Qué son las Variables de Figma?

Las Variables de Figma son la base de cualquier sistema de temas escalable porque admiten Modos - conjuntos de valores paralelos que se pueden cambiar por frame sin tocar un solo componente. A diferencia de los Estilos, que mantienen un valor fijo, una Variable puede resolverse en un color completamente diferente según el Modo activo. Esta distinción importa en el momento en que necesitas lanzar el modo oscuro: sin Modos, cada cambio de tema es una operación manual que se desincroniza a medida que el diseño evoluciona. Si las Variables de Figma son nuevas para ti, la guía completa de design tokens de Figma cubre los fundamentos antes de continuar aquí.

Cómo crear el modo oscuro en Figma

El enfoque recomendado utiliza dos colecciones de Variables - Primitivas y Semántica - y la configuración completa lleva unos 20 minutos desde cero. La mayoría de los equipos se saltan la estructura de dos colecciones en su primer intento y ponen todo en una sola colección, lo que funciona hasta que intentan añadir un tema de marca o un modo de alto contraste y encuentran el sistema imposible de mantener. En Atomize, cada nuevo archivo que incorporamos utiliza exactamente este patrón de dos colecciones porque es la única estructura que escala limpiamente a modos adicionales más adelante. Aquí está el proceso completo de un vistazo:

1. Crea una colección Primitivas en el panel de Variables. Añade todos los valores de color en bruto (cada paso de la paleta) sin modos.
2. Crea una colección Semántica. Añade dos modos: Claro y Oscuro.
3. Para cada token semántico, alias el valor del modo Claro a una Primitiva y el valor del modo Oscuro a una Primitiva diferente.
4. Vincula todos los rellenos, trazos y efectos de los componentes solo a tokens semánticos, nunca a Primitivas directamente.
5. Cambia los modos en cualquier frame de nivel superior para previsualizar instantáneamente el tema oscuro en cada componente.
6. Exporta la colección Semántica como propiedades personalizadas CSS para usar en tu base de código.

Las secciones siguientes cubren cada paso en detalle completo, incluyendo patrones de nomenclatura, pasos exactos de la interfaz de Figma, salida CSS y activación en el lado del navegador. Para ver cómo encaja esto en un sistema de diseño escalable listo para producción, consulta la guía sobre cómo construir un sistema de diseño en Figma.

Mejor configuración: usa una colección Primitivas para valores de color en bruto y una colección Semántica con modos Claro y Oscuro. Vincula los componentes solo a tokens semánticos. Esto mantiene el sistema de diseño con capacidad de temas en todos los modos y evita la deriva de colores codificados entre Figma y el código.

Por qué las Variables superan las anulaciones manuales para el modo oscuro

Las Variables superan las anulaciones manuales para el modo oscuro porque hacen que el tema sea una propiedad estructural del archivo de diseño, no una tarea de mantenimiento. Antes de las Variables, las opciones realistas eran duplicar frames para cada tema, usar propiedades booleanas de los componentes para alternar los estados oscuros, o dejar el modo oscuro completamente en manos de ingeniería - todos enfoques que se rompen a medida que el sistema de diseño crece. El tema a escala requiere que el mismo cambio de valor se propague a cada componente simultáneamente, lo que solo es posible cuando los rellenos están vinculados a tokens en lugar de codificados. Seguir las mejores prácticas del sistema de diseño significa tratar el tema como una preocupación de primera clase en tu arquitectura de tokens - las Variables de Figma lo manejan a nivel estructural para que nada deba rastrearse manualmente.

El mensaje de soporte más común que recibimos en los primeros meses de Atomize era algo así como: ‘Cambié los modos y la mitad de mis componentes no se actualizaron.’ En cada caso que investigamos, la causa raíz era la misma: los rellenos en esos componentes estaban vinculados a una variable Primitiva en lugar de a un token Semántico. Las Primitivas no tienen modos, por lo que cambiar los modos no tiene ningún efecto en ellas. Es un error fácil de cometer cuando se construye rápidamente, y es invisible en el modo claro donde tanto las Primitivas como las Semánticas se resuelven en el mismo valor.

Anulaciones manuales vs Variables + Modos

La arquitectura de dos colecciones

La arquitectura de dos colecciones es la estructura correcta para cualquier sistema de modo oscuro de producción porque separa lo que es un color de lo que significa en la interfaz de usuario. Las Primitivas guardan valores en bruto - cada paso de la paleta, sin modos - mientras que la colección Semántica describe la intención: background/page, text/primary, interactive/default. Cuando se activa el modo oscuro, solo cambian los alias semánticos; las Primitivas y cada componente permanecen intactos. Este es el mismo patrón utilizado por Material Design 3, IBM Carbon y Shopify Polaris - constrúyelo de esta manera una vez y añadir más temas nunca requiere reestructuración.

Esta separación de dos capas es lo que hace que el modo oscuro funcione sin tocar los componentes. Cuando el modo oscuro necesita un fondo diferente, solo el alias semántico cambia - la Primitiva permanece igual y el componente nunca necesita saberlo. Si el relleno de un componente referencia una Primitiva directamente, no puede responder a los cambios de modo; este es el bug de modo oscuro más común en los flujos de trabajo de Figma a código. La guía de design tokens explica la distinción primitiva vs semántica si necesitas más profundidad.

El ejemplo siguiente muestra una arquitectura de tokens completa para un sistema de dos modos claro/oscuro:

/* Colección Primitivas - sin modos, solo valores en bruto */
gray/50    →  #f9fafb
gray/200   →  #e5e7eb
gray/400   →  #9ca3af
gray/700   →  #374151
gray/900   →  #111827
gray/950   →  #030712
blue/400   →  #60a5fa
blue/500   →  #3b82f6
blue/600   →  #2563eb
red/400    →  #f87171
red/500    →  #ef4444

/* Colección Semántica - modo Claro */
background/page       →  gray/50
background/surface    →  white
text/primary          →  gray/950
text/secondary        →  gray/700
border/default        →  gray/200
border/strong         →  gray/400
interactive/default   →  blue/600
interactive/hover     →  blue/500
status/error          →  red/500

/* Colección Semántica - modo Oscuro (mismos nombres, diferentes alias) */
background/page       →  gray/950
background/surface    →  gray/900
text/primary          →  gray/50
text/secondary        →  gray/400
border/default        →  gray/800
border/strong         →  gray/600
interactive/default   →  blue/500
interactive/hover     →  blue/400
status/error          →  red/400

Configurar colecciones en Figma

Configurar dos colecciones en Figma correctamente desde el principio previene los bugs de modo oscuro más comunes antes de que ocurran. Muchos equipos crean una sola colección con modos Claro y Oscuro y se saltan la capa Primitivas, lo que funciona inicialmente pero hace imposible referenciar valores en bruto a través de múltiples colecciones Semánticas o exportar tokens limpios para ingeniería. En el flujo de incorporación de Atomize, creamos la colección Primitivas primero y bloqueamos su alcance antes de tocar las Semánticas - este orden importa porque los alias deben apuntar a variables existentes. Sigue estos pasos para construir la estructura completa de dos colecciones:

1. Abre el panel de Variables en la barra lateral derecha (⌥V en Mac, o haz clic en el ícono de Variables en la barra de herramientas). Crea una colección llamada Primitivas. Añade variables de Color para cada paso de paleta que necesites. No se requieren modos aquí.
2. Crea una segunda colección llamada Semántica. Haz clic en el icono + junto a la pestaña de modo dentro de esta colección para añadir un segundo modo. Nómbralos Claro y Oscuro.
3. Para cada token semántico, haz clic en el campo de valor en la columna del modo Claro y usa el icono de cubo - no el selector de color - para alias a una variable Primitiva. Repite para la columna del modo Oscuro con un alias Primitiva diferente.
4. Agrupa variables usando una barra diagonal como separador de ruta. Escribe background/page como nombre de variable y Figma crea una carpeta de fondo automáticamente. Usa nombres de grupo consistentes en toda la arquitectura de tokens: background/, text/, border/, interactive/, status/*.
5. Establece Alcances de Variable en tokens semánticos para controlar dónde aparecen. background/page debería tener alcance solo en Relleno de Frame y Relleno de Forma. text/primary debería tener alcance solo en Relleno de Texto. Esto evita aplicar el token incorrecto en el contexto incorrecto.
6. Publica ambas colecciones a través del panel Recursos. Cada archivo de componentes en la organización puede referenciar estos tokens a través de la biblioteca compartida.

Nombrar tokens semánticos para el modo oscuro

Los nombres de los tokens semánticos deben describir el papel de un valor en la interfaz de usuario, no su apariencia visual - esta es la regla que mantiene el sistema de nomenclatura honesto en todos los temas. Un nombre basado en el color como background-white se convierte en una mentira en el momento en que el modo oscuro asigna un valor casi negro, y esa mentira se propaga a los nombres de variables CSS, las anotaciones de diseño y la entrega entre equipos. El Grupo Comunitario de Design Tokens del W3C formaliza la nomenclatura basada en roles en su especificación precisamente porque los nombres basados en valores se rompen en el primer límite de tema. Nombra cada token semántico por lo que hace, y el sistema permanece legible independientemente de cuántos modos añadas.

Nomenclatura de tokens semánticos - basada en roles vs basada en valores

Exportar tokens de modo oscuro a CSS

Exportar tokens de modo oscuro a CSS es el paso que cierra la brecha entre lo que muestra Figma y lo que renderiza el navegador - hazlo mal y los tokens se desvían entre el archivo de diseño y la base de código en cuestión de días. Los equipos de ingeniería necesitan propiedades personalizadas CSS que reflejen la estructura exacta de la colección Semántica en Figma, con los valores Claro como predeterminados de :root y los valores Oscuro como anulaciones con alcance. Tokens Studio lee las Variables directamente desde Figma y produce JSON conforme a DTCG que Style Dictionary transforma en CSS, SCSS o TypeScript; la API REST de Variables de Figma proporciona los mismos datos sin un plugin si prefieres una canalización personalizada. Consulta la guía de plugins de Figma para una comparación de herramientas de exportación.

La salida CSS mapea cada Variable semántica a una propiedad personalizada. Los valores del modo Claro se convierten en las declaraciones :root predeterminadas; los valores del modo Oscuro los anulan bajo un selector [data-theme="dark"]:

/* Ejemplo: variables CSS para modo oscuro - predeterminado claro + anulación oscura */

:root {
  --background-page: #f9fafb;
  --background-surface: #ffffff;
  --text-primary: #030712;
  --text-secondary: #374151;
  --border-default: #e5e7eb;
  --border-strong: #9ca3af;
  --interactive-default: #2563eb;
  --interactive-hover: #3b82f6;
  --status-error: #ef4444;
}

[data-theme="dark"] {
  --background-page: #030712;
  --background-surface: #111827;
  --text-primary: #f9fafb;
  --text-secondary: #9ca3af;
  --border-default: #1f2937;
  --border-strong: #4b5563;
  --interactive-default: #3b82f6;
  --interactive-hover: #60a5fa;
  --status-error: #f87171;
}

Los componentes referencian variables CSS en toda la hoja de estilos - sin valores hex codificados en ningún lugar. Ese único vínculo es lo que permite que toda una interfaz de usuario responda a un cambio de tema con un solo cambio de atributo en el elemento raíz. Lograr una paridad fiable del sistema de diseño entre Figma y el código depende de este tipo de fuente única de verdad a nivel de tokens. Si quieres automatizar la configuración de Variables y el flujo de exportación de tokens en Figma - crear colecciones Primitivas y Semánticas, escanear rellenos no vinculados y sincronizar los cambios de tokens con tu base de código - Atomize lo gestiona directamente dentro de Figma sin salir de la herramienta de diseño.

Cambio de tema en el navegador

El cambio de tema en el lado del navegador es donde la arquitectura de tokens de Figma da sus frutos - un solo cambio de atributo en la raíz del documento activa cada anulación de propiedad personalizada CSS simultáneamente. Dos patrones cubren la gran mayoría de casos de uso de producción: prefers-color-scheme, que lee la configuración del SO automáticamente sin JavaScript, y el atributo data-theme, que permite a los usuarios anular esa preferencia con un interruptor manual persistido en localStorage. La mayoría de las aplicaciones que tienen un cambio de tema combinan ambos: predeterminado a la preferencia del SO, luego permitir que el usuario la anule. Elegir el patrón correcto para tu producto determina cuánto JavaScript necesitas y cuánto control esperan los usuarios.

/* Ejemplo: modo oscuro automático via preferencia del SO */
@media (prefers-color-scheme: dark) {
  :root {
    --background-page: #030712;
    --background-surface: #111827;
    --text-primary: #f9fafb;
    --text-secondary: #9ca3af;
    --border-default: #1f2937;
    --interactive-default: #3b82f6;
    --status-error: #f87171;
  }
}

/* Ejemplo: interruptor de tema JavaScript con persistencia en localStorage */

// 1. Leer la preferencia almacenada o detectar desde el SO
const stored = localStorage.getItem('theme');
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const theme = stored ?? (prefersDark ? 'dark' : 'light');

// 2. Aplicar al cargar la página
document.documentElement.setAttribute('data-theme', theme);


// 3. Manejador de alternancia
function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  const next = current === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', next);
  localStorage.setItem('theme', next);
}

prefers-color-scheme vs atributo data-theme

La referencia MDN de prefers-color-scheme cubre el soporte del navegador en detalle. Una nota importante de accesibilidad: los requisitos de contraste de WCAG 2.1 se aplican de forma independiente a cada modo. Un tema oscuro que cumple los requisitos de contraste no hereda el estado aprobado del tema claro - ambos deben validarse por separado.

Extender a más modos

La arquitectura de dos colecciones se extiende limpiamente a cualquier número de temas porque la capa Semántica es lo único que cambia cuando se añade un nuevo modo. Añadir soporte de accesibilidad de alto contraste significa una nueva columna de modo en la colección Semántica; añadir una variante de marca de etiqueta blanca significa una columna más por marca. El límite práctico no es el de Figma - admite hasta 40 modos por colección - sino la sobrecarga cognitiva de gestionar demasiadas combinaciones en un solo lugar. Mantén cada preocupación en su propia colección Semántica: Claro/Oscuro en una, Marca A/Marca B en otra, y apílalas usando la superposición de conjuntos de tokens de Tokens Studio o la canalización de transformación multifuente de Style Dictionary para temas multiplataforma a escala.

Un modo de fallo que vale la pena nombrar explícitamente: cuando los equipos combinan un eje de tema de Color (Claro/Oscuro) y un eje de Densidad (Compacto/Predeterminado) dentro de la misma colección Semántica, Figma crea cuatro combinaciones de modo - Claro+Compacto, Claro+Predeterminado, Oscuro+Compacto, Oscuro+Predeterminado. El lienzo lo maneja correctamente, pero la exportación CSS produce cuatro bloques de selectores separados que son difíciles de anular de forma independiente en producción. Cada usuario de Atomize que alcanzó este patrón eventualmente dividió Color y Densidad en colecciones separadas y las apilaron en el tiempo de exportación. Es una reestructuración única que evita el dolor de mantenimiento CSS continuo.

Solución de problemas de variables en modo oscuro en Figma

¿Por qué no cambia mi componente cuando cambio los modos?

La causa más probable es que el relleno del componente referencia una variable Primitiva directamente en lugar de un token Semántico. Las Primitivas no tienen modos, por lo que cambiar los modos no tiene ningún efecto en ellas. Abre la capa problemática en el panel de Variables, encuentra el relleno que no está cambiando y vuelve a vincularlo al token Semántico correspondiente. Para grandes bibliotecas de componentes con docenas de componentes, Atomize puede escanear todo el archivo de Figma y marcar todas las capas que referencian Primitivas directamente - más rápido que auditar cada componente manualmente.

¿Por qué los colores del modo oscuro no se actualizan en las instancias de componentes?

Las anulaciones de instancias en Figma pueden bloquear que los cambios de modo se propaguen. Si un relleno fue anulado manualmente en una instancia específica, esa anulación tiene prioridad sobre el cambio de modo. Haz clic derecho en la instancia y selecciona Restablecer todas las anulaciones, luego intenta cambiar los modos de nuevo. En el futuro, evita anular rellenos en instancias - usa alias de tokens en su lugar.

¿Por qué los tokens Primitivos no cambian entre Claro y Oscuro?

Las Primitivas son constantes por diseño - no deben tener modos, y cambiar los modos no debería afectarlas. Si esperas que una Primitiva cambie con el tema, el problema subyacente es que falta la capa Semántica. Crea un token Semántico que alias la Primitiva correcta por modo, luego vincula los componentes al token Semántico en lugar de a la Primitiva.

Errores comunes en el modo oscuro en Figma

• Vincular componentes directamente a variables Primitivas. Si un relleno de botón referencia blue/600 en lugar de interactive/default, ese relleno no puede responder a los cambios de modo sin una anulación manual.
• Usar nombres basados en valores como nombres semánticos. Un token llamado background-white o gray-200-border es engañoso en modo oscuro y produce nombres de variables CSS confusos en la base de código.
• Mezclar preocupaciones en una sola colección. Combinar claro/oscuro con variantes de marca y modos de densidad en una sola colección crea una matriz de modos que crece rápidamente de forma inmanejable. Mantén cada dimensión en su propia colección.
• Omitir los Alcances de Variable. Sin alcances, background/page aparece en los menús desplegables de relleno de texto y text/primary aparece en los selectores de relleno para formas. Los alcances restringen cada token a los tipos de propiedad donde pertenece.
• Publicar sin probar los componentes en modo. Antes de publicar una actualización de biblioteca, cambia el modo activo en un frame de alto nivel y revisa visualmente todos los estados de los componentes para ambos temas.
• Codificar valores hex en cualquier parte del diseño. Cualquier relleno, trazo o efecto que omita el sistema de tokens no responderá a los cambios de modo y crea una deriva inmediata entre el archivo de Figma y la base de código.

Veredicto final - Modo Oscuro en Figma

La arquitectura de dos colecciones - Primitivas sin modos, Semánticas con modos Claro y Oscuro - es la forma más limpia y mantenible de construir el modo oscuro en Figma. Los componentes se vinculan solo a tokens semánticos; cambiar los temas se convierte en un único cambio de atributo tanto en Figma como en el navegador. Antes de publicar la librería temática, ejecuta Encontrar Valores No Tokenizados para que los rellenos codificados no sobrevivan al cambio de modo. Configúralo correctamente una vez y escala a temas, marcas y plataformas adicionales sin reconstrucción. Si los componentes no responden a los cambios de modo, la solución es casi siempre volver a vincular los rellenos a tokens semánticos en lugar de añadir más complejidad.