02.12 — Arquitetura CSS

CAMADAS DO SISTEMA.

O CSS do sistema Dark n' Black está organizado em camadas com responsabilidades claras. Cada arquivo tem um escopo definido — entender essa hierarquia evita conflitos, duplicação e override acidental.

Stack: Next.js App Router · CSS custom properties · CSS Modules · Zero CSS-in-JS · Zero Tailwind

Hierarquia de Camadas

tokens.css

Custom properties :root — única fonte de verdade

globals.css

@import tokens.css · reset · body · utilitários globais

components.module.css

Classes de componentes · CSS Modules · importado em UI.tsx

layout.tsx

import '@/styles/globals.css' · ponto de entrada único

FLUXO DE DEPENDÊNCIA → tokens.css ← globals.css ← layout.tsx | components.module.css ← UI.tsx ← páginas

Descrição de Cada Camada

01 — Tokens

src/styles/tokens.css

Única fonte de verdade. Define todas as custom properties CSS do sistema: cores, tipografia, espaçamento, layout.

Contém

+Custom properties :root { --nome: valor }

+@import das Google Fonts (Bebas Neue, Oswald, DM Sans, JetBrains Mono)

+Tokens de cor: pretos, gold e variantes, cinzas, status

+Tokens de tipografia: famílias e escala de tamanhos

+Tokens de espaçamento: escala 8px base

+Tokens de layout: nav-height, sidebar-width, content-max

Não contém

−Nenhuma regra de estilo aplicada a elementos

−Nenhuma classe CSS

−Sem seletores além de :root

02 — Globals

src/styles/globals.css

Estilos base aplicados a elementos HTML. Importa tokens.css. Nunca deve ser importado mais de uma vez.

Contém

+@import ./tokens.css (sempre primeiro)

+Reset universal: margin, padding, box-sizing

+Estilos do body: background, cor, fontes, font-smoothing

+::selection, ::-webkit-scrollbar custom

+Utilitários globais: .noise-overlay, .prose, .page-layout, .page-content

+Links e botões: color: inherit, cursor: pointer

Não contém

−Classes de componentes (ficam em components.module.css)

−Animações (ficam inline ou em CSS local do componente)

−Media queries além do layout base

03 — Componentes

src/styles/components.module.css

CSS Modules para os componentes de UI. Importado apenas em UI.tsx. Os nomes de classe são gerados com hash para evitar colisão.

Contém

+Classes de todos os componentes do sistema (Btn, Badge, Card, etc.)

+Modificadores via composição: .btn + .btnGold

+Estados hover e focus dos componentes

+Variantes por contexto: .ruleBoxDo, .ruleBoxDont, .ruleBoxInfo

Não contém

−Tokens declarados aqui (todos vêm de tokens.css via var())

−Estilos de layout de página

−Classes utilitárias genéricas

04 — Entry Point

src/app/layout.tsx

Root layout do Next.js — importa globals.css uma única vez. Todo o sistema de estilos inicia aqui.

Contém

+import '@/styles/globals.css' (única importação global)

+Estrutura HTML: html, body, noise-overlay

+TopNav e layout principal das páginas

Não contém

−CSS inline de tokens (use sempre var())

Ordem de Importação

src/app/layout.tsx — único ponto de entrada

// 1. Importação global — UMA VEZ, no root layout
import '@/styles/globals.css'
// globals.css já importa tokens.css internamente

// 2. NÃO importe globals.css em páginas individuais
// 3. NÃO importe tokens.css separadamente (globals já faz isso)

// Para componentes individuais, use CSS Modules:
// import styles from '@/styles/components.module.css'

src/styles/globals.css — importação interna

/* Sempre primeiro — tokens devem existir antes de serem usados */
@import './tokens.css';

/* Depois vêm os estilos que consomem os tokens */
body {
  background: var(--black-rich);
  color: var(--white);
}

Como Estender o Sistema

Adicionando tokens novos — em tokens.css

:root {
  /* Adicione APÓS os tokens existentes, nunca sobrescrevendo */
  --meu-token-novo: #valor;

  /* Nomeie seguindo a convenção: --categoria-variante */
  --client-accent: #ff5500;  /* acento de um cliente específico */
}

Adicionando um componente — em components.module.css

/* Siga o padrão existente: nome em camelCase, modificadores compostos */
.meuComponente {
  background: var(--black-card);
  border: 1px solid var(--border);
  padding: var(--space-md);
  font-family: var(--font-body);
}

.meuComponenteDestaque {
  border-left: 3px solid var(--gold);
}

/* NUNCA coloque valores hardcoded — sempre var(--token) */

Adicionando estilo de página — inline no .tsx

// Em páginas do App Router, estilos inline são a prática padrão
// Eles também usam var(--token) — nunca valores hardcoded

export default function MinhaPage() {
  return (
    <div>
      <h1 style={{
        fontFamily: 'var(--font-display)',  // não 'Bebas Neue'
        fontSize: 64,                        // ou var(--text-hero)
        color: 'var(--white)',               // não #f0ece4
      }}>
        TÍTULO
      </h1>
    </div>
  )
}

Convenções de Nomenclatura

Padrão

Contexto

Exemplos

--categoria

Token raiz

--gold, --white, --border

--categoria-variante

Token com variação

--gold-light, --black-card, --space-sm

--categoria-estado

Token de estado

--status-success, --status-error

.componenteNome

Classe base

.btn, .card, .badge

.componenteNomeVariante

Modificador

.btnGold, .cardFeatured, .badgeFilled

Adicione, nunca sobrescreva. Se precisar mudar um valor de token para um projeto específico, declare um token novo com nome próprio. Sobrescrever --gold quebra todos os componentes que dependem dele.

Sem valores fora de tokens. Nenhum #c8a44e ou 16px hardcoded em nenhum arquivo CSS ou style prop. Se o token não existe, crie-o primeiro em tokens.css.

← AnteriorTokens Próximo →Motion