Desde su incorporación oficial en CSS Variables Module Level 3, las custom properties (también conocidas como variables CSS) han transformado la manera de escribir estilos, permitiendo crear temas dinámicos, reutilizar valores y interactuar con JavaScript sin necesidad de preprocesadores.

1. Sintaxis básica

/* Definición */
:root {
  --color-primary: #0069d9;
  --spacing-unit: 1rem;
}
/* Uso */
.button {
  background-color: var(--color-primary);
  padding: var(--spacing-unit);
}

Las variables se definen con el prefijo -- y se acceden mediante la función var(). El selector :root actúa como nivel global, pero cualquier elemento puede declarar su propio conjunto de variables, heredándolas o sobrescribiéndolas.

2. Alcance, herencia y cascada

.card {
  --bg-card: #fff;
  background: var(--bg-card);
}
section {
  --bg-card: #f8f9fa; /* sobrescribe dentro de 
 */
}

3. Fallbacks y valores por defecto

La función var() permite especificar un valor alternativo que se usará cuando la variable no esté definida o su valor sea inválido:

color: var(--text-color, #333); /* #333 como fallback */

4. Modificar variables desde JavaScript

El API CSSStyleDeclaration.setProperty() permite cambiar el valor de una variable en tiempo real, lo que abre la puerta a temas oscuros, animaciones y configuraciones de usuario.

// Cambiar el color primario de toda la página
document.documentElement.style.setProperty('--color-primary', '#ff5722');
// Alternar tema claro/oscuro
const toggle = () => {
  const isDark = document.documentElement.dataset.theme === 'dark';
  document.documentElement.dataset.theme = isDark ? 'light' : 'dark';
  document.documentElement.style.setProperty('--bg-page', isDark ? '#212529' : '#fff');
  document.documentElement.style.setProperty('--text-color', isDark ? '#f8f9fa' : '#212529');
};

5. Creación de temas y componentes reutilizables

Definir un conjunto de variables en :root o en un atributo data-theme permite construir sistemas de diseño escalables.

/* Tema claro */
[data-theme="light"] {
  --bg-page: #fff;
  --text-color: #212529;
  --primary: #0d6efd;
}
/* Tema oscuro */
[data-theme="dark"] {
  --bg-page: #212529;
  --text-color: #f8f9fa;
  --primary: #6610f2;
}
body { background: var(--bg-page); color: var(--text-color); }
.btn-primary { background: var(--primary); border-color: var(--primary); }

Con un solo cambio de atributo data-theme en el html o body, toda la UI adopta el nuevo estilo sin recargar la página.

6. Compatibilidad con navegadores

Las custom properties están soportadas en todas las versiones modernas de Chrome, Edge, Firefox, Safari y Opera. Para Internet Explorer 11 y versiones antiguas se necesita un polyfill como css-vars-ponyfill.

• Chrome 49+, Firefox 31+, Safari 9.1+, Edge 15+
• IE 11: solo mediante polyfill, sin soporte de calc() dentro de var() en algunos casos.

7. Rendimiento y mejores prácticas

• Evita redefinir variables en cada elemento: declara en niveles altos (:root o contenedores temáticos) y reutilízalas.
• Usa unidades relativas (rem, em) en variables de espacio para que el redimensionamiento de fuente se propague automáticamente.
• Limita el número de variables globales a un conjunto esencial (colores, tipografía, breakpoints) para reducir la carga de cálculo del motor de renderizado.
• Prefiere valores estáticos en variables críticas de layout (por ejemplo, --grid-columns) para evitar re‑flujos innecesarios al cambiar valores con JS.

8. Depuración de variables CSS

Las herramientas de desarrollo de Chrome/Firefox muestran las variables en la pestaña Computed. Para inspeccionar valores en tiempo real, abre la consola y ejecuta:

getComputedStyle(document.documentElement).getPropertyValue('--color-primary');

Si una variable no se aplica, verifica:

1. Ortografía del nombre (--color-primary vs --color‑primary).
2. Alcance: la variable está definida en un contenedor que no es ancestro del elemento objetivo.
3. Fallbacks: si el valor es inválido, la función var() caerá al fallback.

9. Seguridad y accesibilidad

Las variables CSS no introducen riesgos de ejecución, pero pueden afectar la legibilidad si se usan para colores de contraste bajo. Siempre verifica el contraste con herramientas como WebAIM Contrast Checker.

Para usuarios que prefieren modos de alto contraste, expón un prefers-contrast media query y ajusta variables en consecuencia:

@media (prefers-contrast: more) {
  :root { --text-color: #000; --bg-page: #fff; }
}

10. Casos de uso del mundo real

• Sistemas de diseño multitema: Shopify, Material‑UI y Tailwind utilizan variables para cambiar colores y tipografía.
• Componentes de UI reutilizables: botones, tarjetas y modales que heredan tamaños y colores mediante variables.
• Animaciones basadas en variables: transiciones de colores o espaciamiento que se pueden controlar con transition: var(--duration, 0.3s).
• Control de accesibilidad: cambiar la escala tipográfica mediante --font-scale y aplicar font-size: calc(1rem * var(--font-scale)).

Conclusión

Las custom properties son una herramienta poderosa que combina la flexibilidad de los preprocesadores con la capacidad de ser manipuladas en tiempo real por el navegador. Adoptarlas mejora la mantenibilidad, reduce la dependencia de herramientas de build y abre la puerta a interfaces más dinámicas y accesibles.

Empieza definiendo un conjunto mínimo de variables globales, crea temas mediante atributos data-* y aprovecha la API de JavaScript para ofrecer personalización al usuario. Con estos pasos tendrás una base sólida para escalar tus proyectos CSS al siguiente nivel.