As propriedades personalizadas CSS – frequentemente conhecidas como variáveis CSS – representam a funcionalidade mais revolucionária do CSS moderno para a criação de folhas de estilo robustas, de fácil manutenção e altamente tematizáveis. Ao contrário das variáveis de pré-processadores como Sass ou LESS, que desaparecem após a compilação, as propriedades personalizadas CSS são ativas e dinâmicas no navegador. Elas podem ser facilmente aplicadas a qualquer elemento, adaptam-se a media queries e podem ser manipuladas em tempo real com JavaScript, abrindo um universo de possibilidades para interfaces interativas e flexíveis.

Sintaxe Fundamental

Definindo e Utilizando Propriedades Personalizadas
/* Define on :root for global scope */
:root {
  --color-primary: #6366f1;
  --color-bg: #0f172a;
  --color-text: #e2e8f0;
  --radius: 12px;
  --shadow: 0 4px 24px rgba(0, 0, 0, 0.3);
  --font-sans: 'Inter', system-ui, sans-serif;
}

/* Use with var() */
.card {
  background: var(--color-bg);
  color: var(--color-text);
  border-radius: var(--radius);
  box-shadow: var(--shadow);
  font-family: var(--font-sans);
}

/* Fallback value */
.card {
  color: var(--color-text, #ffffff);
}

Escopo e Herança

As propriedades personalizadas seguem o fluxo natural da cascata CSS e são herdadas pelos elementos filhos. Essa característica as torna ideais para a tematização em nível de componente, permitindo que você defina estilos base e os ajuste facilmente em contextos específicos.

Variáveis com Escopo
/* Global defaults */
:root {
  --btn-bg: #6366f1;
  --btn-text: #ffffff;
  --btn-radius: 8px;
}

/* Override for a specific section */
.danger-zone {
  --btn-bg: #ef4444;
  --btn-text: #ffffff;
}

/* The button component uses the same variable names */
.btn {
  background: var(--btn-bg);
  color: var(--btn-text);
  border-radius: var(--btn-radius);
}

/* Buttons inside .danger-zone automatically turn red */

Modo Escuro com Propriedades Personalizadas

Tema Claro e Escuro
/* Light theme (default) */
:root {
  --bg: #ffffff;
  --bg-secondary: #f8fafc;
  --text: #1e293b;
  --text-muted: #64748b;
  --border: #e2e8f0;
  --accent: #6366f1;
}

/* Dark theme */
[data-theme="dark"] {
  --bg: #0f172a;
  --bg-secondary: #1e293b;
  --text: #e2e8f0;
  --text-muted: #94a3b8;
  --border: rgba(255, 255, 255, 0.1);
  --accent: #818cf8;
}

/* System preference detection */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg: #0f172a;
    --bg-secondary: #1e293b;
    --text: #e2e8f0;
    --text-muted: #94a3b8;
    --border: rgba(255, 255, 255, 0.1);
    --accent: #818cf8;
  }
}

Integração com JavaScript

Lendo e Escrevendo Variáveis CSS com JS
// Read a CSS variable
const accent = getComputedStyle(document.documentElement)
  .getPropertyValue('--accent').trim();

// Set a CSS variable
document.documentElement.style.setProperty('--accent', '#10b981');

// Theme toggle
function toggleTheme() {
  const current = document.documentElement.dataset.theme;
  document.documentElement.dataset.theme = current === 'dark' ? 'light' : 'dark';
  localStorage.setItem('theme', document.documentElement.dataset.theme);
}

Sistema de Design Tokens

Escala de Espaçamento e Tipografia
:root {
  /* Spacing scale */
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */
  --space-12: 3rem;     /* 48px */

  /* Font sizes */
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;

  /* Responsive font sizes */
  --text-hero: clamp(2rem, 5vw, 3.5rem);
}

Melhores Práticas

  • **Use nomes semânticos** — Prefira `--cor-primaria` em vez de `--azul-500`. Isso permite alterar a cor real sem a necessidade de renomear a variável em todo o projeto, facilitando a manutenção.
  • **Defina todos os tokens de design em `:root`** para garantir consistência global em sua aplicação.
  • **Restrinja variáveis específicas de componentes** ao seletor do próprio componente, evitando vazamento de estilos e promovendo a modularidade.
  • **Sempre forneça valores de fallback** para propriedades críticas: utilize `var(--cor, #000)`. Isso assegura que seus estilos permaneçam robustos, mesmo que a variável não seja definida.
  • **Utilize propriedades personalizadas para tudo que possa mudar** — cores, espaçamentos, fontes, sombras, raios de borda (border-radius) e durações de animação. Isso centraliza o controle e simplifica futuras atualizações de design.

Experimente Nossas Ferramentas CSS Gratuitas

Minifique e embeleze seu código CSS instantaneamente.