Propriedades personalizadas do CSS para temas: herança, fallbacks e @property

O que é

Uma propriedade personalizada (custom property) é qualquer declaração cujo nome começa com --; var(--name, fallback) substitui o valor dela em outra declaração. O guia da MDN afirma que as propriedades personalizadas participam da cascata e são herdadas do elemento pai, que var() só pode aparecer dentro de valores de propriedades (não em seletores, nomes de propriedades nem em condições de media queries e container queries) e que uma substituição inválida se comporta de forma diferente do CSS inválido comum: em vez de descartar a declaração, o navegador usa o valor inicial ou herdado da propriedade. @property registra uma propriedade personalizada com syntax, uma flag inherits e um initial-value, o que a torna verificada quanto ao tipo e animável.

Por que importa

Temas (cores da marca, densidade, modo escuro, estilos por tenant) passam a ser uma questão de redefinir algumas propriedades em um escopo (:root, [data-theme="dark"], a raiz de um componente) em vez de duplicar regras. Como os valores vivem na cascata, podem ser definidos em estilos inline, em JavaScript com style.setProperty e por subárvore, e todas as regras que os leem são atualizadas de uma vez.

Como aplicar

• Defina duas camadas: tokens brutos (--blue-600: #2563eb) e papéis semânticos (--color-accent: var(--blue-600)); os componentes consomem apenas papéis, e os temas redefinem apenas papéis.
• Defina os valores padrão em :root e sobrescreva-os em um elemento de escopo; evite padrões no nível do componente que, sem que se perceba, acabam virando os valores reais.
• Use o argumento de fallback para propriedades que a página hospedeira pode não definir (var(--btn-bg, #333)); a página sobre var() documenta fallbacks aninhados.
• Registre com @property as propriedades que precisam ser animadas ou ter segurança de tipos e dê a elas um initial-value; propriedades não registradas não têm tipo e são animadas de forma discreta.
• Use um prefixo nos nomes ao distribuir componentes (--acme-btn-bg); todas as propriedades personalizadas compartilham um único namespace na cascata.
• Armazene números sem unidade somente se todo consumidor os multiplicar (calc(var(--gap) * 1px)); o valor é substituído como tokens, não convertido.

Armadilhas

A regra da substituição inválida é silenciosa: color: var(--size) com --size: 16px resulta na cor herdada, não em um erro, e o fallback não ajuda, porque a variável está definida. Propriedades personalizadas não podem controlar condições de media queries, então os breakpoints continuam literais. Uma propriedade definida em :root é herdada por tudo, o que é conveniente para temas e confuso para estado local de componente; mantenha o estado local na raiz do componente. Valores definidos por JavaScript são strings e só são validados quando usados.

Onde o var() é resolvido

Uma propriedade personalizada é substituída no elemento em que é declarada, no momento do valor computado, e os descendentes herdam o resultado. Assim, --color-accent: var(--blue-600) em :root é herdada já como a cor resolvida, e redefinir --blue-600 em [data-theme="dark"] ou na raiz de um componente não altera --color-accent ali; o alias mantém o valor computado em :root. Os temas precisam redefinir as propriedades de papel (--color-accent) no seu escopo, ou redeclarar os aliases junto com uma paleta trocada. O sintoma desse erro, um tema com escopo cujas cores continuam as da raiz, parece um problema de especificidade, mas não é.