Variáveis CSS: de var() a temas e @property

Guia de variáveis CSS (custom properties)

Variáveis CSS: sintaxe, escopo, temas, JavaScript, @property | We.Inc

Custom properties do CSS explicadas com um tema claro e escuro ao vivo feito só de variáveis, getPropertyValue e setProperty no JavaScript, @property, @theme do Tailwind v4 e armadilhas comuns.

Declare uma variável CSS com dois hífens, --brand: #2563eb;, normalmente dentro de :root para que a página inteira a enxergue, e leia com var(--brand). Um segundo argumento é o fallback: var(--brand, blue). As variáveis são herdadas como color, então redefinir uma em uma seção muda o valor para tudo o que está dentro dela, o que torna os temas baratos.

Sintaxe em resumo

Tarefa
Código

Declarar globalmente
:root { --gap: 1rem; }

Usar
padding: var(--gap);

Fallback
var(--gap, 16px)

Sobrescrever localmente
.card { --gap: 0.5rem; }

Ler no JS
getComputedStyle(el).getPropertyValue('--gap')

Escrever no JS
el.style.setProperty('--gap', '2rem')

Este guia cobre declaração, escopo e fallback, depois um seletor de tema em que só as variáveis mudam, uma ferramenta que lê e escreve variáveis pelo JavaScript nesta mesma página, propriedades registradas com @property, como o Tailwind v4 transforma o tema dele em variáveis e os erros que fazem var() falhar em silêncio.

Alterne a demo de tema. O markup nunca muda, só os valores de seis variáveis.
Na ferramenta de JavaScript, escolha uma variável, leia o valor atual, defina um novo e veja a amostra se atualizar.
Copie os trechos abaixo para tokens, fallbacks e @property.

Nomeie tokens pela função, não pela aparência: --color-danger dura mais que --red-500 quando a marca vira laranja.
Mantenha um sistema de duas camadas: valores brutos da paleta e, por cima, tokens semânticos que apontam para eles. Os componentes usam só a camada semântica.
Nomes de custom properties diferenciam maiúsculas de minúsculas. --Brand e --brand são duas variáveis diferentes.
Use um fallback quando um componente puder ser colocado em uma página que não define os seus tokens.

Perguntas frequentes

Qual é a diferença entre variáveis CSS e variáveis Sass?

As variáveis Sass são substituídas quando a folha de estilo é compilada e somem do resultado. As custom properties do CSS existem no navegador em tempo de execução, são herdadas pelo DOM, podem variar por elemento e podem ser alteradas pelo JavaScript ou por uma regra de media query depois que a página carrega.

Posso usar uma variável CSS em uma media query?

Não. var() não é permitido na condição de uma regra @media, porque as media queries são avaliadas sem um elemento do qual herdar. Mas você pode mudar o valor de uma variável dentro de um bloco de media query, que é a forma usual de deixar tokens responsivos.

Por que minha variável não funciona?

Confira a grafia e as maiúsculas, se a variável está definida no elemento ou em um ancestral e se o valor final é válido para a propriedade. Se o valor substituído for inválido, a declaração fica inválida no momento do valor computado e a propriedade volta ao valor herdado ou inicial, não à sua regra anterior.

Dá para animar variáveis CSS?

Uma variável não registrada é tratada como string, então ela troca no meio do caminho em vez de interpolar. Registre-a com @property e uma syntax como <color> ou <angle>, e o navegador consegue interpolá-la suavemente em transições e animações.

As variáveis CSS são suportadas em todo lugar?

Custom properties e var() funcionam em todos os principais navegadores há anos. @property é mais recente: o Firefox o adicionou na versão 128, em 2024, então consulte o caniuse se você dá suporte a versões antigas e mantenha um fallback não registrado.

Escopo e herança

Uma custom property é uma propriedade herdada comum. Definida em :root, ela chega a todos os elementos. Definida em .card, vale só para aquele card e seus descendentes, e ali vence o valor de :root porque o valor mais próximo é o herdado.
É isso que deixa as variantes de componentes curtas. Um botão lê var(--btn-bg), e .btn-danger apenas define --btn-bg: var(--color-danger). Sem um segundo conjunto de regras para cada estado.

Inválido no momento do valor computado

O navegador não consegue verificar uma declaração com var() durante o parsing, já que o valor é desconhecido até ser substituído. Então margin: var(--size) com --size: red é aceito no parsing e só falha depois.
Quando falha, a propriedade é tratada como unset. Para uma propriedade herdada como color, isso significa a cor do pai; para margin, significa 0. Uma regra de margin válida anterior na sua folha de estilo não volta, o que surpreende quem está acostumado aos fallbacks normais da cascata.

Tokens de tema usados na demo

Valores claros e escuros

Token
Claro
Escuro

--color-bg

--color-surface

--color-text

--color-muted

--color-accent

--color-border

Escopo e fallback, ao vivo

Sobrescrita local e fallback

O segundo card redefine --accent para si mesmo. O terceiro usa uma variável que ninguém definiu, então aparece a cor de fallback.

Tema claro e escuro só com variáveis

Um único conjunto de regras de componentes. O tema é outro conjunto de valores, escolhido pela configuração do sistema ou por um atributo data-theme.

Lendo e escrevendo variáveis no JavaScript

getPropertyValue e setProperty

Leia o valor computado de qualquer elemento. Escreva em :root para uma mudança global, ou em um elemento para afetar só a subárvore dele.

@property: variáveis tipadas e animáveis

Animar o ângulo de um gradiente

Registrar --angle como <angle> permite que o navegador o interpole. Sem o registro, o gradiente saltaria em vez de girar.

@theme do Tailwind v4

Tokens viram utilitários e variáveis

No Tailwind v4, variáveis em @theme geram utilitários como bg-brand e também são emitidas como variáveis CSS reais que você pode usar com var().

Armadilhas

O que costuma confundir

Problema
Por quê
Solução

var() em condição de @media
Condições de media não são avaliadas por elemento
Mude a variável dentro do bloco de media

Valor com unidade falha
--n: 4; e depois width: var(--n)px gera '4 px'
Use calc(var(--n) * 1px)

Propriedade cai para initial
Inválida no momento do valor computado
Confira o valor substituído, adicione um fallback

Variável ignorada em url()
url(var(--x)) não é permitido
Guarde o url(...) inteiro na variável

Variável derivada ignora uma sobrescrita
:root { --big: calc(var(--base) * 2) } é resolvida em :root, então .card { --base: 5px } não muda --big
Declare --big de novo em .card também, ou calcule onde ela é usada

Tema claro e escuro, só com variáveis

Tema

modo claro

modo escuro

Relatório semanal

Pedidos acima da semana passada

pedidos de exemplo

Ver detalhes

A única coisa que muda

Copiar CSS

Ler e escrever variáveis pelo JavaScript

A caixa de exemplo abaixo usa var(--demo-accent, #2563eb) na borda e var(--demo-radius, 8px) nos cantos. Defina qualquer uma das variáveis e a caixa muda.

Nome da variável

Novo valor

O nome de uma custom property começa com dois hífens, por exemplo --demo-radius.

Ler

Definir

Remover

Teste --demo-radius

Caixa de exemplo

(não definida)

Comece grátis · Sem cartão de crédito