Propiedades personalizadas de CSS para temas: herencia, valores de reserva y @property

Qué es

Una propiedad personalizada es cualquier declaración cuyo nombre empieza por --; var(--name, fallback) sustituye su valor dentro de otra declaración. La guía de MDN indica que las propiedades personalizadas están sujetas a la cascada y heredan del elemento padre, que var() solo puede aparecer dentro de valores de propiedad (no en selectores, nombres de propiedad ni en condiciones de consultas de medios o de contenedor), y que una sustitución inválida se comporta de forma distinta a un CSS inválido corriente: en lugar de descartar la declaración, el navegador usa el valor inicial o heredado de la propiedad. @property registra una propiedad personalizada con una syntax, un indicador inherits y un initial-value, lo que permite comprobar su tipo y animarla.

Por qué importa

Aplicar un tema (colores de marca, densidad, modo oscuro, estilos por inquilino) pasa a ser cuestión de redefinir un puñado de propiedades en un ámbito (:root, [data-theme="dark"], la raíz de un componente) en lugar de duplicar reglas. Como los valores viven en la cascada, pueden fijarse desde estilos en línea, desde JavaScript con style.setProperty, y por subárbol, y toda regla que los lea se actualiza a la vez.

Cómo aplicarlo

• Definir dos capas: tokens en bruto (--blue-600: #2563eb) y roles semánticos (--color-accent: var(--blue-600)); los componentes solo consumen roles, y los temas solo redefinen roles.
• Fijar los valores por defecto en :root y sobrescribirlos en un elemento de ámbito; evitar valores por defecto a nivel de componente que terminan convirtiéndose, sin que se note, en los valores reales.
• Usar el argumento de reserva para propiedades que una página anfitriona podría no definir (var(--btn-bg, #333)); la página de var() documenta los valores de reserva anidados.
• Registrar con @property las propiedades que deban animarse o requieran comprobación de tipo, y darles un initial-value; las propiedades no registradas carecen de tipo y se animan de forma discreta.
• Usar un espacio de nombres al distribuir componentes (--acme-btn-bg); todas las propiedades personalizadas comparten un único espacio de nombres en la cascada.
• Guardar números sin unidad solo si todo consumidor los multiplica (calc(var(--gap) * 1px)); un valor se sustituye como token, no se convierte.

Trampas

La regla de sustitución inválida actúa en silencio: color: var(--size) con --size: 16px da como resultado el color heredado, no un error, y el valor de reserva no ayuda porque la variable sí está definida. Las propiedades personalizadas no pueden condicionar consultas de medios, así que los puntos de ruptura siguen siendo literales. Una propiedad definida en :root la hereda todo, lo cual resulta cómodo para los temas y confuso para el estado local de un componente; conviene mantener el estado local en la raíz del componente. Los valores fijados desde JavaScript son cadenas de texto y no se validan hasta que se usan.

Dónde se resuelve var()

Una propiedad personalizada se sustituye en el elemento donde se declara, en el momento de calcular el valor, y los descendientes heredan el resultado. Por eso, --color-accent: var(--blue-600) en :root se hereda ya como el color resuelto, y redefinir --blue-600 en [data-theme="dark"] o en la raíz de un componente no cambia allí --color-accent; el alias conserva el valor calculado en :root. Los temas deben redefinir las propiedades de rol (--color-accent) en su propio ámbito, o volver a declarar los alias junto con la paleta sustituida. El síntoma de hacerlo mal —un tema con ámbito cuyos colores siguen siendo los de la raíz— parece un problema de especificidad, pero no lo es.