Variáveis no Sass: $cor, !default e quando usar var()

Variável Sass começa com $ e existe somente enquanto o compilador trabalha. Custom property começa com --, atravessa o build e chega ao navegador. As duas guardam valores, mas vivem em momentos diferentes; escolher só pela aparência do nome produz tema que não muda ou CSS maior do que precisava.

Os exemplos foram enviados ao Dart Sass 1.103.1 com este formato de comando:

npx --yes sass@1.103.1 --stdin --no-source-map --style=expanded

O comando não imprime um rótulo de sucesso: com entrada válida, o stdout contém somente o CSS compilado que aparece depois de cada exemplo.

Se o comando ainda não funciona, volte à aula de instalação do Sass. Se $ e -- parecem equivalentes, compare também com variáveis CSS.

A variável que desaparece na compilação

O compilador substitui cada referência pelo valor atual. Nem o nome $brand nem a declaração aparecem na saída:

$brand: #6d28d9;

.button {
  background: $brand;
}

Isso é perfeito para uma decisão fechada no build: uma proporção, o número de colunas geradas ou um token que muda entre pacotes compilados. Também significa que JavaScript, atributos HTML e media queries do usuário não conseguem alterar $brand depois.

A custom property que chega ao navegador

Agora escreva o mesmo valor como propriedade CSS. Sass preserva a declaração e o var():

:root { --brand: #6d28d9; }
.button { background: var(--brand); }

Como --brand participa da cascata, um elemento pode herdá-la e outro pode sobrescrevê-la. É a escolha natural para tema claro/escuro, marca recebida do servidor ou valor alterado em tempo de execução. O custo é manter a expressão no CSS e deixar a resolução para o navegador.

Reatribuição: Sass é imperativo

Variáveis Sass seguem a ordem do arquivo. Uma regra já gerada não volta no tempo quando o valor muda:

$brand: #6d28d9;
.light { color: $brand; }

$brand: #a78bfa;
.dark { color: $brand; }

Em CSS, uma custom property é declarativa: se duas declarações disputam o mesmo elemento, a cascata decide o valor usado por todas as referências. No Sass, cada referência é substituída durante a leitura sequencial.

!default: um padrão que aceita configuração

O marcador !default atribui apenas quando a variável ainda não existe ou vale null. Neste teste, a cor do consumidor venceu o padrão da biblioteca:

$brand: #0f766e;
$brand: #6d28d9 !default;

.button { color: $brand; }

Em um módulo real, a configuração entra por @use "library" with ($brand: #0f766e). !default é parte da API do módulo: documente quais tokens podem ser configurados. Espalhá-lo em qualquer arquivo só esconde uma ordem de imports difícil de entender.

Escopo local e shadowing

Uma variável criada dentro de uma regra normalmente é local. Se ela tem o mesmo nome de uma global, ocorre shadowing: a local vence dentro do bloco sem alterar a global.

$brand: #6d28d9;

.card {
  $brand: #0f766e;
  color: $brand;
}

.button { color: $brand; }

Esse isolamento impede que um componente mude acidentalmente um token global. Existe !global, mas o uso frequente é sinal de estado compartilhado demais; prefira retorno de função, parâmetro de mixin ou configuração de módulo.

O erro mais comum: variável fora do escopo

Aqui $local nasce dentro de .card e é lida depois do fechamento. O compilador aponta exatamente os seis caracteres desconhecidos:

.card {
  $local: #6d28d9;
  color: $local;
}

.button { color: $local; }

Mover a declaração para o topo resolve se o valor realmente for global. Se não for, mantenha o uso no mesmo escopo. Não copie a variável para dois lugares: a duplicação elimina justamente o benefício do token.

Misturar Sass e custom properties com intenção

As ferramentas não são rivais. Sass pode escolher um valor inicial e publicá-lo como custom property. A interpolação #{} manda o compilador inserir o valor dentro da declaração CSS:

$brand: #6d28d9;

:root {
  --brand: #{$brand};
}

Depois, o navegador ainda pode sobrescrever --brand. Esse padrão funciona bem quando o pacote Sass distribui padrões, mas a aplicação oferece temas em runtime.

Uma regra prática para decidir

Faça uma pergunta: o valor precisa mudar sem recompilar? Se sim, escolha custom property. Se não, e o valor alimenta loops, maps, funções ou configuração de módulos, a variável Sass é adequada. Para simples constantes que aparecem uma única vez, talvez nenhuma variável seja necessária.

Há ainda uma decisão de manutenção: um token deve carregar significado, não a aparência acidental de hoje. $color-purple-600 descreve implementação; $action-primary descreve intenção. Se a marca trocar roxo por azul, o segundo nome continua correto. Para custom properties vale a mesma regra. Separe tokens primitivos, como --violet-600, dos semânticos, como --action-bg, e faça o componente consumir o semântico. Essa camada parece trabalho extra em quatro botões, mas evita trocar centenas de referências quando o sistema cresce.

Também não guarde tudo numa variável. Valores que aparecem uma vez e não têm significado compartilhado ficam mais claros escritos no lugar. O objetivo não é substituir números por nomes; é criar um contrato para decisões que realmente se repetem ou precisam ser configuradas.

Este pequeno contrato deixa a fronteira explícita:

$grid-columns: 12;
$asset-path: "/assets";

:root {
  --brand: #6d28d9;
  --space-fluid: clamp(1rem, 2vw, 2rem);
}

Como $grid-columns e $asset-path não são usados, eles não geram declaração alguma. --brand e --space-fluid, por outro lado, permanecem no CSS.

Na próxima lição, essas variáveis entram em seletores aninhados. Antes de avançar, compile os exemplos e confira a saída: aprender Sass é sempre comparar o que você escreveu com o CSS que realmente chegou ao navegador. O mapa geral da linguagem está no guia completo de Sass.