CSS Que Fica Onde Você Coloca

Todo desenvolvedor frontend já viveu esse pesadelo: você escreve uma regra CSS perfeitamente razoável como p { color: red }, e de repente parágrafos do outro lado da sua aplicação ficam vermelhos. Você não quis dizer todos os parágrafos. Quis dizer os que estão aqui, neste componente. Mas o CSS não se importa com suas intenções — ele é global por natureza, e cada regra que você escreve tem o potencial de alcançar lugares que você jamais esperou.

Frameworks tentaram resolver isso de dezenas de formas: convenções de nomenclatura BEM, CSS Modules, bibliotecas CSS-in-JS, frameworks utilitários. Cada abordagem tem suas desvantagens — algumas adicionam verbosidade, outras adicionam custo em tempo de execução, algumas exigem ferramentas de build, e todas requerem disciplina.

O Svelte adota uma abordagem fundamentalmente diferente. Quando você escreve CSS dentro do bloco <style> de um componente Svelte, esse CSS é automaticamente delimitado por escopo ao componente. Sem convenções de nomenclatura para memorizar. Sem bibliotecas extras para instalar. Sem overhead em tempo de execução. O compilador cuida de tudo em tempo de build, gerando nomes de classes únicos que garantem que seus estilos não possam afetar acidentalmente outros componentes.

Este artigo cobre exatamente como esse mecanismo funciona, quais são as regras e limites, e os poucos lugares onde o sistema de escopo se comporta de forma diferente do CSS puro. O artigo de acompanhamento cobre o que fazer quando você precisa que os estilos ultrapassem esses limites.

Como o Compilador Delimita o Escopo dos Seus Estilos

O escopo de CSS do Svelte é uma transformação em tempo de compilação. O compilador gera um hash único com base nos estilos do componente, adiciona esse hash como uma classe a cada elemento visado pelo seu CSS e reescreve os seletores para incluir o hash. O resultado é um componente estilizado por regras que só podem corresponder aos seus próprios elementos.

Um Exemplo Concreto

Aqui está o que você escreve:

<p>Hello!</p>
<span>World</span>

<style>
	p {
		color: blue;
	}
</style>

E aqui está o que o Svelte gera (simplificado):

<p class="svelte-abc123">Hello!</p>
<span>World</span>

<style>
	p.svelte-abc123 {
		color: blue;
	}
</style>

Três coisas a observar na saída. Primeiro, o hash (svelte-abc123) é adicionado como classe ao <p> porque o CSS o visa. Segundo, <span> não recebe hash — nada no CSS deste componente visa span, então não há razão para marcá-lo. Terceiro, o seletor CSS p se torna p.svelte-abc123, que só corresponde a um <p> com exatamente aquela classe de hash. Nenhum <p> de outro componente a terá.

Essa transformação é determinística e acontece inteiramente em tempo de build sem nenhum overhead em tempo de execução.

Dois Componentes, Sem Colisão

O benefício prático aparece imediatamente quando dois componentes estilizam o mesmo tipo de elemento:

<!-- Greeting.svelte -->
<p>Hello!</p>

<style>
	p {
		color: blue;
		font-weight: bold;
	}
</style>

<!-- Warning.svelte -->
<p>Watch out!</p>

<style>
	p {
		color: red;
		font-style: italic;
	}
</style>

Ambos compilam para seletores com seus próprios hashes únicos. p.svelte-abc123 só corresponde ao parágrafo de Greeting. p.svelte-xyz789 só corresponde ao de Warning. Você pode usar seletores simples e semânticos — p, h1, button, .card — sem se preocupar com colisões.

As Três Regras de Escopo

Entender o escopo com precisão requer saber o que "pertencer a um componente" significa. Há três regras que definem o limite.

Regra 1: Estilos se aplicam a elementos no próprio template do componente

As regras CSS de um componente alcançam os elementos HTML escritos diretamente em seu <script> + template:

<!-- Parent.svelte -->
<div class="wrapper">
	<p>This paragraph IS styled by Parent</p>
	<Child />
</div>

<style>
	.wrapper {
		padding: 1rem;
	}
	p {
		color: green;
	}
</style>

A regra p estiliza o parágrafo escrito no template de Parent. Ela não alcança elementos <p> dentro de <Child />.

Regra 2: Os estilos de um pai não penetram componentes filhos

Mesmo seletores descendentes não cruzam o limite do componente:

<!-- Parent.svelte -->
<div class="wrapper">
	<Child />
</div>

<style>
	/* This does NOT style <p> elements inside Child */
	.wrapper p {
		color: green;
	}
</style>

O seletor compilado .wrapper.svelte-abc p.svelte-abc exige que ambos os elementos carreguem o mesmo hash de escopo. O <p> dentro de <Child> tem um hash diferente (o próprio hash de Child), então ele não corresponderá. O limite é firme.

Regra 3: Conteúdo criado no pai é estilizado pelo pai

Quando você passa conteúdo para um componente filho via snippets, esse conteúdo ainda é escrito no template do pai — portanto, os estilos do pai se aplicam a ele:

<!-- Parent.svelte -->
<Child>
	<!-- This <p> is written in Parent's template -->
	<p>Snippet paragraph</p>
</Child>

<style>
	/* This DOES style the paragraph above */
	p {
		color: green;
	}
</style>

Os estilos seguem onde a marcação é criada, não onde é renderizada. O snippet viaja para Child, mas o hash de escopo de Parent viaja junto. Isso é intuitivo quando você pensa: da perspectiva do compilador, o <p> é um elemento de Parent.

Avisos de Estilos Não Utilizados

O Svelte mantém suas folhas de estilo enxutas ao avisar quando uma regra CSS não corresponde a nenhum elemento no template do componente:

<p>Hello</p>

<style>
	p {
		color: blue;
	}

	/* ⚠️ Warning: Unused CSS selector ".sidebar" */
	.sidebar {
		width: 200px;
	}
</style>

Isso detecta erros de digitação e regras restantes de refatorações — ambas fontes comuns de inchaço nas folhas de estilo. O compilador sabe exatamente quais elementos existem no template e pode verificar se cada seletor tem um alvo.

Quando o Aviso É um Falso Positivo

O compilador não consegue ver classes adicionadas em tempo de execução por JavaScript ou bibliotecas de terceiros:

<script>
	let el = $state(null)

	$effect(() => {
		if (el) el.classList.add('active') // added programmatically
	})
</script>

<div bind:this={el}>Content</div>

<style>
	/* ⚠️ Unused CSS selector — but it IS used at runtime */
	.active {
		background: yellow;
	}
</style>

A solução é usar :global(.active) para estilos que visam classes adicionadas dinamicamente. Isso diz tanto ao compilador quanto ao navegador para aplicar a regra independentemente do escopo — abordado no próximo artigo.

Animações de Keyframe com Escopo

@keyframes recebem escopo no componente usando a mesma abordagem de hash:

<div class="spinner"></div>

<style>
	.spinner {
		animation: spin 1s linear infinite;
	}

	/* "spin" is scoped — it won't clash with a "spin" keyframe in another component */
	@keyframes spin {
		from {
			transform: rotate(0deg);
		}
		to {
			transform: rotate(360deg);
		}
	}
</style>

O Svelte renomeia o keyframe internamente (para algo como spin-abc123) e ajusta a propriedade animation para corresponder. Dois componentes podem definir @keyframes spin sem que um interfira no outro. Se você precisar que um keyframe seja referenciável globalmente — por exemplo, por uma biblioteca de terceiros — você prefixo o nome com -global-, o que é abordado no artigo sobre Estilos Globais.

Aninhamento de CSS

O aninhamento de CSS moderno (agora suportado em todos os principais navegadores) funciona naturalmente dentro do escopo do Svelte:

<nav class="sidebar">
	<a href="/home">Home</a>
	<a href="/docs">Docs</a>
</nav>

<style>
	.sidebar {
		display: flex;
		flex-direction: column;
		gap: 0.25rem;

		a {
			/* Scoped: only <a> elements inside .sidebar in THIS component */
			padding: 0.5rem 1rem;
			border-radius: 4px;
			color: #374151;
			text-decoration: none;

			&:hover {
				background: #f3f4f6;
			}
		}
	}
</style>

O hash de escopo é aplicado tanto a .sidebar quanto ao seletor aninhado a, mantendo tudo dentro do limite do componente. O aninhamento que visa elementos fora do limite do componente (usando :global()) é abordado no artigo sobre Estilos Globais.

Especificidade: Ligeiramente Maior do que Parece

Como o Svelte acrescenta uma classe a cada seletor com escopo, suas regras compiladas são ligeiramente mais específicas do que os seletores que você escreveu:

/* What you write — specificity: 0,0,1 (one element) */
p {
	color: blue;
}

/* What Svelte generates — specificity: 0,1,1 (one class + one element) */
p.svelte-abc123 {
	color: blue;
}

Isso é quase sempre inofensivo. Mas importa se você estiver misturando estilos de componentes com escopo e folhas de estilo globais — uma regra de componente com escopo vencerá uma regra de elemento simples em uma folha de estilo global mesmo que a regra global seja carregada depois.

Há uma nuance adicional que vale conhecer: quando a mesma classe de escopo precisa aparecer mais de uma vez em um seletor complexo, o Svelte usa :where(.svelte-abc123) para as ocorrências subsequentes. :where() sempre tem especificidade zero, o que significa que a especificidade do seletor não continua acumulando conforme o seletor cresce. Essa é uma escolha deliberada do compilador — mantém a especificidade previsível independentemente de quão complexos sejam seus seletores.

Erros Comuns

Esperando que estilos do pai alcancem os filhos

<!-- Avoid: won't style <h1> or <p> inside Header or Content -->
<div class="page">
	<Header />
	<Content />
</div>

<style>
	.page h1 {
		font-size: 2rem;
	}
	.page p {
		line-height: 1.7;
	}
</style>

O seletor compilado .page.svelte-abc h1.svelte-abc exige que ambos os elementos tenham o mesmo hash. Elementos dentro de componentes filhos possuem hashes diferentes. Os seletores não vão corresponder.

A solução depende do que você está tentando realizar. Se quiser estilizar elementos que você controla, estilize-os dentro de seus próprios componentes. Se precisar alcançar o DOM não controlado (bibliotecas de terceiros, conteúdo {@html}), use :global(). Se precisar que um pai influencie a aparência de um filho sem quebrar o encapsulamento, use propriedades customizadas do CSS. As três abordagens são abordadas nos artigos a seguir.

Referência Rápida

<!-- Scoped to this component — can use simple element selectors freely -->
<style>
	p {
		color: blue;
	}
	.card {
		padding: 1rem;
	}
	h1 {
		font-size: 2rem;
	}

	/* CSS nesting works — still scoped */
	.sidebar {
		a {
			color: #374151;
		}
		a:hover {
			background: #f3f4f6;
		}
	}

	/* Keyframes are scoped too — no clash with same name in other components */
	@keyframes spin {
		from {
			transform: rotate(0deg);
		}
		to {
			transform: rotate(360deg);
		}
	}
</style>

O Que Vem a Seguir?

O escopo é a base, mas é apenas metade do quadro. O próximo artigo aborda o que acontece quando você precisa que o CSS vá além do limite do componente:

Estilos Globais — :global(), blocos :global {}, keyframes -global-, importações de arquivos externos e quando usar cada abordagem
Vinculação Dinâmica de Classe — Tornando a atribuição de classes reativa com o atributo class e a diretiva class: