Declarar y leer

Su nombre técnico es propiedad personalizada (custom property). Se declara como cualquier propiedad, pero el nombre empieza con dos guiones: --accent: oklch(0.52 0.2 290). Para leerla se usa la función var(): background: var(--accent).

1. Distinguen mayúsculas--accent ≠ --Accent--accent y --Accent son dos variables distintas.
2. Se heredaninheritsSi la declarás en un elemento, todos sus descendientes la pueden leer.
3. Se leen tardevar()CSS no revisa el valor al declararla. Recién lo interpreta cuando una propiedad la lee con var().

Mové los controles y mirá cómo el botón y la tarjeta cambian juntos: los dos leen las mismas variables de .tema. Después pisá --accent en la tarjeta y quitá --radius. Las marcas naranjas muestran el valor de cada variable donde se lee: el relleno de la tarjeta, su borde y la esquina del botón.

.tema {
  --accent: oklch(0.52 0.1 190);
  --radius: 12px;
  --space: 16px;
}

.boton {
  background: var(--accent);
  color: white;
  border-radius: var(--radius, 8px);
  padding: calc(var(--space) / 2) var(--space);
}

.tarjeta {
  border: 2px solid var(--accent);
  border-radius: var(--radius, 8px);
  padding: var(--space);
}

<div class="[--accent:oklch(0.52_0.1_190)] [--radius:12px] [--space:16px]">
  <button class="bg-(--accent) text-white rounded-(--radius,8px) px-(--space) py-[calc(var(--space)/2)]">Anotarme</button>
  <div class="border-2 border-(--accent) rounded-(--radius,8px) p-(--space)">Este mes: Los años, de Annie Ernaux</div>
</div>

Alcance y cascada

Una variable vive en el elemento que la declara y en sus descendientes. Sigue la cascada normal: especificidad, orden y herencia, igual que color. Por eso declararla en .tarjeta cambia el acento solo dentro de la tarjeta, y el botón sigue con el de .tema.

El segundo argumento de var() es el valor de respaldo (fallback). Con var(--radius, 8px), si --radius no está definida en ningún ancestro, se usan 8px. Es lo que pasa en la demo al quitarla.

1.tema {
2  --space: red;            /* válido: no se revisa al declarar */
3}
4
5.tarjeta {
6  padding: 24px;
7  padding: var(--space);   /* inválido al calcularse: queda en 0 */
8}

Ojo con ese caso: si la variable existe pero su valor no sirve para la propiedad, la declaración es inválida al calcular el valor (invalid at computed-value time). No se usa el respaldo ni el padding: 24px anterior; la propiedad se comporta como unset, y como padding no se hereda, vale 0.

Usos prácticos

1. Tokens de diseño:rootColores, radios y espacios con nombre en :root, para cambiarlos en un solo lugar.
2. Temasprefers-color-schemeRedefinís los mismos tokens dentro de @media (prefers-color-scheme: dark) y todo lo que los lee cambia. Este sitio lo hace así.
3. Cálculoscalc(var(--space) * 2)Con --space: 16px da 32px. Para sumar una unidad a un número usá calc(var(--n) * 1px); var(--n)px no funciona.

1:root {
2  --bg: oklch(0.99 0 0);
3  --text: oklch(0.2 0 0);
4}
5
6@media (prefers-color-scheme: dark) {
7  :root {
8    --bg: oklch(0.2 0 0);
9    --text: oklch(0.95 0 0);
10  }
11}
12
13body {
14  background: var(--bg);
15  color: var(--text);
16}

Una variable común no tiene tipo, así que el navegador no sabe interpolarla y una transición sobre ella salta de golpe. Con @property la registrás con un tipo (syntax), si se hereda (inherits) y un valor inicial (initial-value). Así se puede animar:

1@property --angle {
2  syntax: "<angle>";
3  inherits: false;
4  initial-value: 0deg;
5}
6
7.flecha {
8  transform: rotate(var(--angle));
9  transition: --angle 300ms;
10}
11
12.flecha:hover {
13  --angle: 90deg;
14}

En Tailwind

En Tailwind v4 los valores del tema ya son variables: --spacing o --color-white viven en :root. Para declarar una propia en un elemento se usa una propiedad arbitraria entre corchetes, y para leerla, la clase con el nombre entre paréntesis.

1<div class="[--accent:oklch(0.52_0.2_290)] [--space:16px]">
2  <button class="bg-(--accent) text-white rounded-(--radius,8px)
3                 px-(--space) py-[calc(var(--space)/2)]">
4    Guardar
5  </button>
6  <div class="[--accent:oklch(0.52_0.2_10)]
7              border-2 border-(--accent) p-(--space)">
8    Tarjeta
9  </div>
10</div>