Variables CSS: de var() a temas y @property

Guía de variables CSS (custom properties)

Variables CSS: sintaxis, ámbito, temas, JavaScript, @property | We.Inc

Las custom properties de CSS explicadas con un tema claro y oscuro en vivo hecho solo con variables, getPropertyValue y setProperty en JavaScript, @property, @theme de Tailwind v4 y trampas habituales.

Declara una variable CSS con dos guiones, --brand: #2563eb;, normalmente dentro de :root para que toda la página la vea, y léela con var(--brand). Un segundo argumento es el valor de respaldo: var(--brand, blue). Las variables se heredan igual que color, así que redefinir una en una sección la cambia para todo lo que contiene, lo que hace que los temas salgan baratos.

La sintaxis de un vistazo

  • Tarea
  • Código
  • Declarar de forma global
  • :root { --gap: 1rem; }
  • Usar
  • padding: var(--gap);
  • Respaldo
  • var(--gap, 16px)
  • Sobrescribir localmente
  • .card { --gap: 0.5rem; }
  • Leer en JS
  • getComputedStyle(el).getPropertyValue('--gap')
  • Escribir en JS
  • el.style.setProperty('--gap', '2rem')

Esta guía cubre cómo declarar, delimitar el ámbito y usar valores de respaldo; después, un selector de tema donde solo cambian variables, una herramienta que lee y escribe variables desde JavaScript en esta misma página, las propiedades registradas con @property, cómo Tailwind v4 convierte su tema en variables y los errores que hacen que var() falle sin avisar.

  • Cambia el tema de la demo. El marcado no cambia nunca, solo los valores de seis variables.
  • En la herramienta de JavaScript, elige una variable, lee su valor actual, luego asigna uno nuevo y mira cómo se actualiza la muestra.
  • Copia los fragmentos de abajo para tokens, valores de respaldo y @property.
  • Nombra los tokens por su función, no por su aspecto: --color-danger sobrevive a --red-500 cuando la marca se vuelve naranja.
  • Mantén un sistema de dos capas: valores crudos de la paleta y, encima, tokens semánticos que apuntan a ellos. Los componentes solo usan la capa semántica.
  • Los nombres de las custom properties distinguen mayúsculas y minúsculas. --Brand y --brand son dos variables distintas.
  • Usa un valor de respaldo cuando un componente pueda acabar en una página que no define tus tokens.

Preguntas frecuentes

¿Qué diferencia hay entre las variables CSS y las variables de Sass?

Las variables de Sass se sustituyen al compilar la hoja de estilos y desaparecen del resultado. Las custom properties de CSS existen en el navegador en tiempo de ejecución, se heredan a través del DOM, pueden variar por elemento y se pueden cambiar desde JavaScript o con una regla de media query después de cargar la página.

¿Puedo usar una variable CSS en una media query?

No. var() no está permitido en la condición de una regla @media, porque las media queries se evalúan sin un elemento del que heredar. Sin embargo, sí puedes cambiar el valor de una variable dentro de un bloque de media query, que es la forma habitual de hacer que los tokens sean adaptables.

¿Por qué no funciona mi variable?

Comprueba la ortografía y las mayúsculas, que la variable esté definida en el elemento o en un ancestro, y que el valor final sea válido para la propiedad. Si el valor sustituido no es válido, la declaración pasa a ser inválida en el momento del valor calculado y la propiedad vuelve a su valor heredado o inicial, no a tu regla anterior.

¿Se pueden animar las variables CSS?

Una variable sin registrar se trata como una cadena, así que cambia de golpe a mitad de la transición en lugar de interpolarse. Regístrala con @property y una sintaxis como <color> o <angle>, y el navegador podrá interpolarla con suavidad en transiciones y animaciones.

¿Las variables CSS funcionan en todas partes?

Las custom properties y var() funcionan en todos los navegadores principales desde hace años. @property es más reciente: Firefox lo añadió en la versión 128 en 2024, así que consulta caniuse si das soporte a versiones antiguas y mantén un respaldo sin registrar.

Ámbito y herencia

  • Una custom property es una propiedad heredada normal. Definida en :root, llega a todos los elementos. Definida en .card, se aplica solo a esa tarjeta y sus descendientes, y ahí gana al valor de :root porque se hereda el valor más cercano.
  • Eso es lo que hace cortas las variantes de componentes. Un botón lee var(--btn-bg), y .btn-danger solo asigna --btn-bg: var(--color-danger). No hace falta un segundo conjunto de reglas para cada estado.

Inválido en el momento del valor calculado

  • El navegador no puede comprobar una declaración con var() al analizarla, porque el valor no se conoce hasta que se sustituye. Así que margin: var(--size) con --size: red se acepta al analizar y solo falla después.
  • Cuando falla, la propiedad se trata como unset. Para una propiedad heredada como color, eso significa el color del padre; para margin, significa 0. Una regla de margin válida anterior en tu hoja de estilos no vuelve a aplicarse, algo que sorprende a quien está acostumbrado a los respaldos normales de la cascada.

Tokens de tema usados en la demo

Valores claros y oscuros

  • Token
  • Claro
  • Oscuro
  • --color-bg
  • --color-surface
  • --color-text
  • --color-muted
  • --color-accent
  • --color-border

Ámbito y respaldo, en vivo

Sobrescritura local y respaldo

La segunda tarjeta redefine --accent para sí misma. La tercera usa una variable que nadie ha definido, así que se ve el color de respaldo.

Tema claro y oscuro solo con variables

Un único conjunto de reglas de componentes. El tema es otro conjunto de valores, elegido por la configuración del sistema o por un atributo data-theme.

Leer y escribir variables en JavaScript

getPropertyValue y setProperty

Lee el valor calculado de cualquier elemento. Escribe en :root para un cambio global, o en un elemento para afectar solo a su subárbol.

@property: variables con tipo y animables

Anima el ángulo de un degradado

Registrar --angle como <angle> permite al navegador interpolarlo. Sin el registro, el degradado saltaría en lugar de girar.

@theme en Tailwind v4

Los tokens se convierten en utilidades y variables

En Tailwind v4, las variables de @theme generan utilidades como bg-brand y además se emiten como variables CSS reales que puedes usar con var().

Trampas habituales

Cosas que confunden a la gente

  • Problema
  • Por qué
  • Solución
  • var() en la condición de @media
  • Las condiciones de media no se evalúan por elemento
  • Cambia la variable dentro del bloque media
  • Falla un valor con unidades
  • --n: 4; y luego width: var(--n)px produce '4 px'
  • Usa calc(var(--n) * 1px)
  • La propiedad vuelve al valor inicial
  • Inválido en el momento del valor calculado
  • Revisa el valor sustituido y añade un respaldo
  • Variable ignorada en url()
  • url(var(--x)) no está permitido
  • Guarda el url(...) completo en la variable
  • Una variable derivada ignora una sobrescritura
  • :root { --big: calc(var(--base) * 2) } se resuelve en :root, así que .card { --base: 5px } no cambia --big
  • Vuelve a declarar --big también en .card, o calcúlalo donde se usa

Tema claro y oscuro, solo con variables

Tema

modo claro

modo oscuro

Informe semanal

Pedidos en alza respecto a la semana pasada

pedidos de ejemplo

Ver detalles

Lo único que cambia

Copiar CSS

Lee y escribe variables desde JavaScript

La caja de muestra de abajo usa var(--demo-accent, #2563eb) para el borde y var(--demo-radius, 8px) para las esquinas. Asigna cualquiera de las dos variables y la caja cambia.

Nombre de la variable

Nuevo valor

El nombre de una custom property empieza con dos guiones, por ejemplo --demo-radius.

Leer

Asignar

Quitar

Prueba --demo-radius

Caja de muestra

(sin definir)

Empieza gratis · Sin tarjeta de crédito

Relacionado: Guías

Producto

Para quién es

Funciones

Recursos

Empresa

Mapa del sitio