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
- z-index y contextos de apilamiento CSS, desmontados en 3D
- Cómo añadir modo oscuro a una web (CSS, Tailwind, Next.js)
- Obtener datos en React y Next.js, comparado en una app
- Data URLs
- Debounce vs throttle, visualizado
- Deferred deep linking
- Micrositios departamentales
- Cómo desplegar una app de React o Next.js
Producto
Para quién es
- Para agencias
- Para freelancers
- Para proveedores de hosting
- Para plataformas SaaS
- Para startups
- Servicios financieros
- Soluciones para salud
Funciones
Recursos
- Blog
- Centro de Ayuda
- Herramientas gratuitas para empresas
- Free UI Components
- Plantillas
- Colecciones de plantillas
- Ejemplos de webs
- Guías
- Comparativas
- Alternativas
- Los mejores
- Reseñas
- Guías de precios
- Casos de uso
- Glosario y guías
- Integraciones
- Desarrolladores
- Benchmark
- Windows App