Cuando el valor no encaja con la sintaxis

Registrar una custom property no impide que alguien le asigne una barbaridad: cualquier declaración --x: loquesea sigue siendo sintácticamente válida y sigue entrando en la cascada. Lo que cambia es qué ocurre después. Sin registro, la barbaridad se guarda y contamina a todos los que la usen; con registro, se rechaza en la propia propiedad y ninguno de sus consumidores se entera. Y de paso, registrar altera el significado de initial, que es la fuente de sorpresas más silenciosa de todo el asunto.

El destino de un valor que no encaja

La comprobación no ocurre al analizar sino al computar, igual que la sustitución de var(). Cuando el valor no encaja con la sintaxis registrada, la custom property queda inválida en tiempo de computación, y su valor pasa a ser el heredado si se registró con inherits: true, o el initial-value si se registró con inherits: false.

@property --radio {
  syntax: "<length>";
  inherits: false;
  initial-value: 8px;
}

.tarjeta {
  --radio: 1.5rem;
  border-radius: var(--radio);      /* 1.5rem */
}

.rota {
  --radio: muy-redondo;             /* rechazado */
  border-radius: var(--radio);      /* 8px, el initial-value */
}

Es exactamente la semántica de unset, aplicada a la custom property en lugar de a la propiedad que la consume. Y esa diferencia de destinatario lo es todo.

Contención frente a propagación

flowchart TB
A[Alguien asigna un valor malo] --> B{La propiedad esta registrada}
B -- No --> C[El valor malo se guarda tal cual]
C --> D[Cada var que lo use produce un valor invalido]
D --> E[Cada propiedad consumidora cae a unset]
E --> F[Sintomas distintos en cada sitio]
B -- Si --> G[El valor se rechaza en la propia propiedad]
G --> H[La propiedad toma el inicial o el heredado]
H --> I[Todos los consumidores reciben un valor correcto]
style F fill:#f38ba8,color:#11111b
style I fill:#a6e3a1,color:#11111b
style G fill:#89b4fa,color:#11111b

La rama roja es lo que hace tan cara la depuración de un sistema de tokens sin registrar. El valor malo se escribe en un sitio y los síntomas aparecen en otros diez, cada uno con su forma: aquí un color heredado del padre, allá un fondo transparente, más allá una abreviada completa que se evapora. Ninguno de esos diez elementos menciona la causa en su panel de estilos, porque la causa está en un ancestro y en una propiedad que ni siquiera aparece en la lista de declaraciones aplicadas.

La rama verde reduce el problema a un solo punto: la propiedad tiene un valor por defecto correcto y el sistema sigue en pie. El defecto sigue existiendo —la tarjeta se ve con el radio equivocado— pero es un defecto localizado y no una cascada de síntomas.

Los casos límite que sorprenden

initial cambia de significado. Éste es el importante. En una propiedad sin registrar, --x: initial la deja garantizadamente inválida, es decir, la borra, y por eso var(--x, reserva) usa la reserva. En una propiedad registrada, --x: initial la pone a su initial-value, que es un valor perfectamente válido, y por tanto var(--x, reserva) ya no usa la reserva nunca.

@property --acento { syntax: "<color>"; inherits: true; initial-value: black; }

.a { --acento: initial; color: var(--acento, red); }
/* Sin registrar seria rojo. Registrada es negro. */

De ahí salen dos consecuencias prácticas: el interruptor de espacio deja de conmutar, como ya sabías, y todos los fallbacks de var() de esa propiedad se vuelven código muerto. No es un problema —la propiedad siempre tiene valor, que era el objetivo— pero conviene borrarlos para que nadie los lea como si hicieran algo.

Las demás palabras clave globales siguen funcionando. inherit, unset y revert hacen lo que esperas sobre una propiedad registrada, teniendo en cuenta su inherits.

Un var() roto dentro del valor también cae al inicial. Si escribes --radio: calc(var(--base) * 2) y --base no existe, el valor entero es inválido en tiempo de computación y --radio toma su initial-value. Otra vez: el error se contiene.

Los valores tocados por una animación tienen restricciones. Si el valor de una custom property procede de una animación en curso, la especificación lo marca y no permite usarlo en las propiedades que controlan la propia animación —duraciones, retardos— porque produciría una dependencia circular. Es un caso raro, pero si alguna vez ves que un animation-duration: var(--d) no aplica en un elemento cuya --d se está animando, ésta es la razón.

Diagnosticarlo

Tres pasos, en orden.

Compara lo declarado con lo calculado. Si el panel de valores calculados muestra exactamente tu initial-value y tú habías declarado otra cosa, la asignación se ha rechazado. Es la señal inequívoca.

Comprueba que la regla @property se registró. Si falta un descriptor obligatorio, la regla se ignora entera y la propiedad funciona como no registrada; entonces el síntoma es el contrario, y verás unset en los consumidores en lugar del inicial. Distinguir los dos casos te dice de golpe si el problema está en el registro o en la asignación.

/* Comprobacion rapida: si esta registrada, el valor calculado esta resuelto. */
getComputedStyle(el).getPropertyValue('--radio');  /* "8px" y no "calc(...)" */

Pon un valor inicial escandaloso mientras depuras. Cambiar temporalmente initial-value a magenta o a 99px convierte un fallo silencioso en uno imposible de pasar por alto, y te dice al instante qué elementos están cayendo al camino de error.