Organizando a folha do portfólio · CSS do zero

O problema aparece devagar

Nas primeiras cem linhas, qualquer organização funciona. Aos poucos aparece o sintoma: para mudar uma cor, você precisa de um seletor mais longo que o anterior. Depois de mais longo, !important.

Isso é especificidade acumulada, e o conserto não é escrever seletores maiores - é organizar a folha de modo que os mais gerais venham antes.

No seu portfólio, a folha já tem umas duzentas linhas escritas em onze aulas, em ordem de aula e não em ordem de cascata. Hoje ela é arrumada.

Nomes que dizem o papel

/* Ruim: o nome descreve a aparência */
.verde { }
.texto-14 { }
.margem-20 { }
.div3 { }

/* Bom: o nome descreve a função */
.selo { }
.cartao { }
.acao { }
.etiqueta { }

A diferença aparece na primeira mudança de design. Quando o realce deixar de ser verde e passar a ser azul, .verde { color: azul } fica no arquivo mentindo; e alguém vai perder tempo com isso.

.selo continua verdadeiro qualquer que seja a cor.

Uma convenção que funciona

/* Bloco */
.cartao { }

/* Parte de um bloco: duas sublinhas */
.cartao__titulo { }
.cartao__ficha { }

/* Variação: dois traços */
.cartao--destaque { }

<article class="cartao cartao--destaque">
  <h3 class="cartao__titulo">Feira do produtor</h3>
  <dl class="cartao__ficha">...</dl>
</article>

Chama-se BEM. Não é obrigatório: mas ter alguma convenção é, e esta tem a vantagem de dizer, só pelo nome, onde a classe vive e o que ela faz.

A ordem do arquivo

/* ===================================
   1. Variáveis
   =================================== */
:root {
  --fundo: #0e1116;
  --realce: #6ee7a5;
  --espaco-3: 1rem;
}

/* ===================================
   2. Reset
   =================================== */
*,
*::before,
*::after {
  box-sizing: border-box;
}

/* ===================================
   3. Base: as tags cruas
   =================================== */
body {
  font-family: var(--fonte);
  line-height: 1.6;
}

/* ===================================
   4. Layout: as estruturas grandes
   =================================== */
.envelope { }
.prosa { }
header { }
footer { }

/* ===================================
   5. Componentes: as peças
   =================================== */
.cartao { }
.acao { }
.selo { }
.etiqueta { }
.grade { }

/* ===================================
   6. Utilidades e preferências
   =================================== */
.apenas-leitor { }

@media (prefers-color-scheme: light) { }
@media (prefers-reduced-motion: reduce) { }

Do geral ao específico. Isso faz a cascata trabalhar a favor: o que vem depois sobrescreve naturalmente, sem precisar de seletor mais forte nem de !important.

E as duas preferências ficam no fim de propósito: elas precisam vencer o que veio antes, e a ordem já faz isso sozinha.

O reset mínimo

*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
}

img,
picture,
video {
  max-width: 100%;
  height: auto;
  display: block;
}

input,
button,
textarea,
select {
  font: inherit;
}

ul[class],
ol[class] {
  list-style: none;
  margin: 0;
  padding: 0;
}

As duas últimas merecem nota.

font: inherit conserta o formulário de contato: campos não herdam a fonte do body por padrão, e sem essa linha eles aparecem na fonte do sistema enquanto o resto do portfólio usa outra.

ul[class] é o truque que evita repetir list-style: none em seis lugares: ele zera só as listas que receberam classe - o menu, a grade, as etiquetas -, e deixa em paz as listas de conteúdo do texto corrido, que devem continuar com marcador.

`@layer`, quando a cascata aperta

@layer reset, base, layout, componentes, utilidades;

@layer base {
  a {
    color: var(--realce);
  }
}

@layer componentes {
  .cartao a {
    color: inherit;
  }
}

A ordem declarada na primeira linha manda: componentes ganha de base mesmo que o seletor seja menos específico. É controle explícito da cascata, e resolve a maior parte dos casos em que se recorreria a !important.

Num portfólio de trezentas linhas, a ordem das seções já basta. Vale conhecer @layer para quando o projeto crescer - e para ler o CSS dos outros.

Comentários que valem

/* ===================================
   Componentes
   =================================== */

/* O cartão de projeto.
   O `margin-top: auto` no rodapé alinha os links de "abrir projeto"
   de todos os cartões, que têm descrições de tamanhos diferentes. */
.cartao footer {
  margin-top: auto;
}

Comentário bom registra a decisão, não o óbvio. /* deixa o texto verde */ acima de color: var(--realce) é ruído. O que salva alguém - inclusive você, em seis meses - é saber por que aquele margin-top: auto existe.

Utilidades, poucas

.apenas-leitor {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}

.centro {
  margin-inline: auto;
}

.pilha {
  display: grid;
  gap: var(--espaco-3);
}

Utilidade é exceção, não estratégia. Meia dúzia resolve; cem transformam o HTML numa folha de estilo escrita dentro do class.

Quando dividir em arquivos

Num site pequeno, um arquivo bem organizado é mais fácil de navegar que cinco. Divida quando começar a doer:

estilos/
├── base.css        (variáveis, reset, tags)
├── layout.css      (envelope, cabeçalho, rodapé)
├── componentes.css (cartão, botão, selo, grade)
└── main.css        (importa os outros)

/* main.css */
@import "base.css";
@import "layout.css";
@import "componentes.css";

A conferência de dez minutos

De tempos em tempos, vale abrir a folha e perguntar:

Existe valor de cor ou espaço escrito na mão fora das variáveis?
Existe !important fora do bloco de prefers-reduced-motion? Por quê?
Existe seletor com mais de três níveis?
Existem duas classes fazendo a mesma coisa com nomes diferentes?
As seis seções ainda estão na ordem?
Algum nome de classe descreve aparência em vez de papel?

No portfólio

Hoje não se acrescenta um efeito: arruma-se o que existe.

reorganize main.css nas seis seções, com os comentários de cabeçalho;
mova todas as variáveis para o :root no topo, e todas as cores soltas para lá;
escreva o reset mínimo completo, com font: inherit e ul[class];
renomeie as classes cujo nome descreva aparência;
adote BEM nos componentes que têm partes: o cartão e a abertura;
escreva um comentário de decisão em cada regra que não é óbvia;
deixe as duas media queries de preferência no fim.

Depois recarregue as seis páginas. Nada pode ter mudado na tela. Se mudou, alguma regra dependia da ordem antiga - e descobrir isso agora é melhor do que descobrir daqui a seis meses.

Exercícios

Reorganize a sua folha na ordem das seis seções e confira que nada mudou na tela.
Procure classes com nome de cor ou de tamanho e renomeie pelo papel.
Escreva o reset mínimo no topo, incluindo font: inherit e ul[class].
Adote a convenção BEM no cartão de projeto.
Escreva um comentário explicando por quê de três regras suas que não são óbvias.
Conte quantos !important existem na sua folha. Para cada um fora do bloco de movimento reduzido, tente resolver mudando a ordem.

Referências

Organizando o CSS - MDN - metodologias e quando cada uma serve
BEM - a convenção de nomes, com exemplos
Modern CSS Reset - Andy Bell - um reset curto e comentado