Design on kenji.blog

Personalização de Tema Hugo: Como Introduzir Tailwind CSS

Sun, 13 Sep 2026 03:00:00 +0900

Introdução: A Poderosa Sinergia entre o Gerador de Sites Estáticos Hugo e o Tailwind CSS

No desenvolvimento moderno de front-end web, equilibrar desempenho e experiência de desenvolvimento (DX: Developer Experience) é uma das prioridades mais importantes em qualquer projeto. A combinação do Hugo, que possui a velocidade de construção mais rápida do mundo entre os geradores de sites estáticos (SSG), com o Tailwind CSS, que trouxe o paradigma inovador de utility-first (utilitário em primeiro lugar), pode ser considerada uma das soluções definitivas para este desafio.

O Hugo é escrito em Go e possui um desempenho impressionante, capaz de concluir a construção de milhares de páginas em apenas short segundos ou até milissegundos. Por outro lado, o Tailwind CSS elimina a troca de contexto entre arquivos CSS e HTML, escrevendo diretamente no HTML inúmeras classes utilitárias predefinidas (como flex, text-center, mt-4), o que acelera a iteração do design.

Neste artigo, explicaremos de forma completa e detalhada o processo de introdução do Tailwind CSS em um tema do Hugo, bem como a construção de um pipeline de assets avançado (Hugo Pipes) usando PostCSS, desde a base da arquitetura até a perspectiva da otimização matemática de desempenho.

1. A Evolução do CSS Utility-First e Orientado a Componentes

Antes de entrar no passo a passo para a introdução do Tailwind CSS, é muito útil entender profundamente a história e a evolução da filosofia de design de CSS, para compreendermos por que devemos usar o Tailwind CSS.

As Limitações do Design CSS Tradicional (BEM e OOCSS)

Antigamente, a melhor prática no desenvolvimento web era dar nomes semânticos às classes. Por exemplo, ao criar um componente de cartão, separávamos o HTML do CSS da seguinte forma:

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">Título</h2>
 <p class="card__description">A descrição vai aqui.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* A partir daqui, estilos mais detalhados continuam */

Esse tipo de design baseado em BEM (Block Element Modifier) funciona bem quando a escala do projeto é pequena, mas geralmente causa os seguintes problemas:

Exaustão e falta de nomes: Toda vez que você cria um componente semelhante, precisa pensar em novos nomes de classes (ex: card-news, card-featured, etc.).
Inchaço do CSS: Toda vez que um novo recurso é adicionado, as linhas de CSS aumentam. Devido ao medo de não saber “onde o CSS está sendo usado”, o código raramente é excluído, acumulando código morto (dead code).
Troca de contexto: Como a estrutura HTML e o estilo CSS são gerenciados em arquivos separados, o número de vezes que você alterna entre as abas no editor aumenta exponencialmente.

A Mudança de Paradigma pelo Tailwind CSS

O Tailwind CSS resolve esses problemas com a abordagem de “combinação de classes utilitárias”. O componente de cartão acima ficaria assim usando o Tailwind CSS:

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">Título</h2>
 <p class="mt-2 text-gray-600">A descrição vai aqui.</p>
 </div>
</div>

Como o próprio nome da classe representa o valor específico do estilo (por exemplo, p-6 significa padding: 1.5rem;), é possível prever o resultado final da renderização apenas olhando o HTML. Além disso, devido ao compilador JIT (Just-In-Time) do Tailwind, apenas as classes realmente utilizadas são extraídas para o arquivo CSS de produção, minimizando o tamanho do arquivo CSS ao extremo.

2. A Arquitetura do Hugo Pipes e PostCSS

Para integrar o Tailwind CSS ao Hugo, é necessário entender o pipeline de processamento de assets chamado Hugo Pipes. O Hugo Pipes é um recurso poderoso que conclui todo o processamento de assets dentro do Hugo, como a compilação de Sass/SCSS, o empacotamento (bundle) e minificação (minify) de JavaScript e a execução do PostCSS, que usaremos nesta ocasião.

O PostCSS é uma ferramenta para transformar CSS usando plugins JavaScript. Na verdade, o próprio Tailwind CSS funciona como um plugin do PostCSS.

Mecanismo de Transformação de AST (Abstract Syntax Tree) pelo PostCSS

Entender como o PostCSS processa o CSS é de grande ajuda ao solucionar problemas. O diagrama Mermaid abaixo ilustra o pipeline desde a leitura do arquivo CSS pelo PostCSS, sua transformação através de plugins, até a saída final do CSS.

flowchart TD
A["CSS Bruto (styles.css)"] -->|Parser| B["AST (Árvore de Sintaxe Abstrata)"]
B --> C["Plugin 1: Tailwind CSS"]
C --> D["Plugin 2: Autoprefixer"]
D --> E["Plugin N: cssnano"]
E -->|Stringifier| F["CSS Compilado e Otimizado"]

Parser (Analisador): Analisa a string CSS bruta fornecida e a converte em uma AST (Árvore de Sintaxe Abstrata), que é uma estrutura de dados manipulável programaticamente.
Plugins (Conjunto de Plugins):
- Tailwind CSS: Verifica os arquivos de modelo (HTML ou Markdown) e adiciona as classes utilitárias usadas como nós na AST. Também expande as diretivas @tailwind.
- Autoprefixer: Consulta o banco de dados do Can I Use e, se necessário, adiciona prefixos de fornecedores (-webkit-, -moz-, etc.) às propriedades da AST.
Stringifier (Conversor para String): Converte a AST, cuja transformação foi concluída, de volta em uma string CSS que o navegador pode interpretar.

3. Configuração do Ambiente e Pré-requisitos

Agora, vamos aos passos reais de introdução. Primeiro, verifique se os softwares necessários estão instalados.

Requisitos Essenciais

Hugo Extended Version: É obrigatório o uso da versão Extended, que, ao contrário do Hugo padrão, inclui a capacidade de processar Sass/SCSS e a integração nativa com o PostCSS. Execute o comando abaixo no terminal e confirme se a string extended está contida nas informações da versão.
1 2 3

hugo version # Exemplo de saída esperada: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js e npm: Dependências como Tailwind CSS e PostCSS rodam no Node.js. Certifique-se de que o Node.js (versão LTS recomendada) esteja instalado.
1 2

node -v npm -v

Instalação de Pacotes npm

Inicialize o npm no diretório raiz do projeto (o mesmo nível do arquivo de configuração do Hugo, hugo.toml) e instale os pacotes necessários.

1
2
3
4
5


# Geração do package.json
npm init -y

# Instalação do Tailwind CSS, PostCSS e Autoprefixer como dependências de desenvolvimento
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Se o postcss-cli não estiver instalado, pode ocorrer um erro quando o Hugo tentar invocar o PostCSS internamente. Como o Hugo Pipes utiliza o postcss-cli internamente, não se esqueça de instalá-lo.

4. Construção dos Arquivos de Configuração (PostCSS e Tailwind CSS)

Após a instalação dos pacotes, criaremos dois arquivos de configuração importantes que controlam o comportamento do projeto. Coloque-os no diretório raiz do projeto.

Criação do tailwind.config.js

Ao executar o comando abaixo no terminal, o arquivo de configuração padrão será gerado.

1

npx tailwindcss init

Abra o arquivo gerado tailwind.config.js no editor e configure a propriedade content. Isso é extremamente importante. O Tailwind vai analisar os arquivos dos caminhos especificados aqui e extrair as classes usadas. Certifique-se de especificar corretamente os arquivos de layout e conteúdo para corresponder à estrutura do projeto do Hugo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Especifica os alvos de verificação de acordo com a estrutura de diretórios do Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Se você estiver usando um tema, também precisa incluir o diretório do tema
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Extensões de cores personalizadas e fontes são feitas aqui
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Adicione plugins oficiais se necessário (ex: plugin Typography)
 // require('@tailwindcss/typography'),
 ],
}

Criação do postcss.config.js

Em seguida, crie o arquivo postcss.config.js na raiz do projeto, que define quais plugins o PostCSS deve executar e em qual ordem.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

Com esta configuração, quando o Hugo chamar o PostCSS, primeiro será processado o Tailwind CSS, e depois o Autoprefixer aplicará os prefixos de fornecedores.

5. Construção do Pipeline de Assets CSS no Hugo

Com a configuração concluída, finalmente integraremos o Tailwind CSS no lado do tema do Hugo.

5-1. Criação do Arquivo CSS de Ponto de Entrada

No diretório assets/css/ (crie-o se não existir), crie o arquivo CSS que servirá como ponto de entrada. Aqui vamos chamá-lo de main.css.

Caminho do arquivo: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Carregamento do estilo base do Tailwind (como CSS reset) */
@tailwind base;

/* Carregamento das classes de componentes */
@tailwind components;

/* Carregamento das classes utilitárias */
@tailwind utilities;

/* Se precisar de CSS personalizado, você pode adicionar aqui,
 mas é recomendável usar o 'extend' no tailwind.config.js sempre que possível */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. Edição do Arquivo de Layout (head.html)

A seguir, a partir dos templates do Hugo, leremos o arquivo CSS acima e descreveremos o pipeline para processá-lo com o PostCSS. Normalmente, você edita o partial template que define o interior da tag <head> (ex: layouts/partials/head.html).

Caminho do arquivo: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- Obtém o assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Definição de opções do PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Pipeline de otimização de assets para ambiente de produção (Production) -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (Compressão) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (Adição de hash para cache busting) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Geração da tag incluindo SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- No ambiente de desenvolvimento (Development), o arquivo não é comprimido (prioridade na velocidade de build) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Explicação do Pipeline e Diagrama Mermaid

Para entender como o código do template Go processa o arquivo CSS, ilustramos abaixo o processo do pipeline.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Espaço de Memória do Hugo"]
B -->|resources.PostCSS| C["PostCSS + Processo JIT do Tailwind"]
C --> D{"hugo.IsProduction ?"}
D -- Sim (Produção) --> E["minify (Remover espaços/quebras)"]
E --> F["fingerprint (Cálculo de hash)"]
F --> G["public/css/main.[hash].css (com SRI)"]
D -- Não (Desenvolvimento) --> H["public/css/main.css"]

resources.Get: Procura o arquivo especificado no diretório assets e o carrega como um objeto de recurso na memória.
resources.PostCSS: Referencia o postcss.config.js na raiz do projeto e aplica o processamento do Tailwind CSS e Autoprefixer no código fonte CSS. No ambiente de desenvolvimento (hugo server), o modo JIT é ativado, gerando rapidamente apenas as classes necessárias ao modificar arquivos.
minify: Durante a compilação para produção (ex: hugo --environment production), remove espaços em branco e comentários desnecessários, minimizando o tamanho do arquivo.
fingerprint: Calcula o hash SHA com base no conteúdo do arquivo e o adiciona ao nome do arquivo (ex: main.ab12cd...css). Isso permite o uso robusto do cache do navegador, além de implementar o “cache busting”, garantindo que os usuários baixem o novo arquivo CSS após uma atualização.
integrity: Usando o valor hash calculado pelo Fingerprint, gera um atributo SRI para prevenir adulterações vindas de CDNs, etc.

6. Análise de Desempenho Matemático na Otimização do CSS

Um dos maiores benefícios de introduzir o Tailwind CSS é a minimização extrema do tamanho do arquivo CSS distribuído. Vamos analisar quantitativamente como isso afeta a performance web (especialmente o First Contentful Paint: FCP) através de um modelo matemático.

Modelo de Redução do Tamanho do Arquivo CSS

Com frameworks CSS convencionais (como Bootstrap), o tamanho do arquivo $S_{original}$ tende a ser grande, pois ele carrega todos os estilos, mesmo os não utilizados (cerca de 150KB a 200KB). Se definirmos $S_{purged}$ como o tamanho após o expurgo (Purge) de classes desnecessárias pelo compilador JIT do Tailwind CSS, podemos usar a taxa de redução $R_{purge}$ para expressá-lo da seguinte forma:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

Em projetos típicos, o $R_{purge}$ atinge quase $0.9$ (redução de 90%), e o $S_{purged}$ cai para algo em torno de 10KB a 20KB.

Além disso, ao distribuir os arquivos, o servidor aplica a compressão (Brotli ou Gzip). Definindo a taxa de compressão como $R_{compress}$ (geralmente entre 0.7 e 0.8), o tamanho final da carga útil (payload) enviada pela rede, $S_{final}$, é calculado da seguinte forma:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

Caminho Crítico de Renderização e Atraso de Rede

O tempo para o navegador pintar o primeiro conteúdo na tela (FCP) pode ser aproximado pela soma do tempo de download do HTML, o tempo de download do CSS e o tempo de renderização.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

Onde:

$RTT$ : Round Trip Time (tempo de latência de ida e volta ao servidor)
$BW$ : Largura de banda da rede (Bandwidth)

Em ambientes com um $BW$ estreito e um grande $RTT$ (como redes móveis com alta latência), a abordagem do Tailwind CSS, que consegue reduzir $S_{final}$ a meros kilobytes, aproxima o valor do termo $\frac{S_{final}}{BW}$ ao extremo de zero, sendo a força motriz por trás de pontuações excepcionais (no Google PageSpeed Insights e afins).

7. Iniciar o Servidor de Desenvolvimento e Verificar o Hot Reload

Quando toda a configuração estiver pronta, inicie o servidor de desenvolvimento do Hugo e certifique-se de que o Tailwind CSS está funcionando corretamente.

1

hugo server -D

Acesse http://localhost:1313/ no seu navegador e confirme que o site é exibido. Tente abrir arquivos de conteúdo em Markdown ou templates do Hugo (arquivos em layouts/) e adicionar algumas classes.

1
2
3
4
5


<!-- Exemplo de aplicação de classes Tailwind para testes -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">Confira o hot reload sendo refletido instantaneamente.</p>
</div>

No exato momento em que você salvar o arquivo, poderá desfrutar do “hot reload”, em que o poderoso observador de arquivos do Hugo e o compilador JIT do Tailwind se unem, reconstruindo o CSS em milissegundos e recarregando automaticamente o navegador.

Solução de Problemas: Quando os Estilos Não São Refletidos

Se as alterações não forem aplicadas, verifique os seguintes pontos:

A configuração de caminho em content no tailwind.config.js Se o caminho do arquivo para a varredura estiver incorreto, o Tailwind não conseguirá detectar as classes usadas nesse arquivo e não as colocará no CSS. Especialmente se estiver usando um tema, certifique-se de que o caminho do diretório do tema não foi esquecido.
Erro do PostCSS Se houver um erro nos logs do servidor do Hugo no terminal dizendo Error: failed to transform resource: PostCSS not found, pode significar que o npm install não foi executado corretamente, ou o pacote postcss-cli está ausente.
Limpeza do Cache do Hugo Raramente, o cache do Hugo pode causar problemas mantendo CSS antigo. Pare o servidor e reinicie com hugo server --ignoreCache, ou tente excluir o diretório temporário do SO (como /tmp/hugo_cache/).

8. Build para Produção e Aprimoramentos Avançados

Ao fazer o deploy do site para um servidor de produção (Netlify, Vercel, GitHub Pages, Cloudflare Pages, etc.), é preciso configurar as variáveis de ambiente para executar o pipeline de otimização focado na produção.

1
2


# Exemplo de comando de compilação de produção
NODE_ENV=production hugo --minify --environment production

Ao adicionar a flag --environment production, o bloco {{ if hugo.IsProduction }} no arquivo head.html será executado, e o processo de minificação e fingerprinting será aplicado.

Estilização do Markdown com o Plugin Typography

Em sites de blogs e de documentações como o Hugo, você não pode adicionar classes diretamente aos elementos HTML puros gerados a partir do Markdown (como <h1>, <p>, <ul>, etc.). Para esses casos, o Plugin Typography oficial do Tailwind se mostra incrivelmente útil.

Instalação do plugin

1

npm install -D @tailwindcss/typography

Adição no tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

Aplicação no template Apenas adicionando a classe prose (e preferencialmente variantes de tamanho e cor) ao contêiner onde o texto do artigo será impresso, um estilo padrão bonito será aplicado.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

Assim, não há mais a necessidade de escrever à mão seletores CSS complexos (.article-content h2 { ... }), e a modularidade do componente é mantida perfeitamente.

9. Conclusão: Construção de um Ecossistema de Front-End Altamente Sustentável

Parabéns! Com isso, o pipeline de assets de desenvolvimento web perfeito — que combina o motor de geração de site estático ultrarrápido do Hugo, os recursos modernos de estilo do Tailwind CSS e a extensibilidade do PostCSS — foi concluído.

A grande vantagem desta arquitetura é que “a configuração só precisa ser feita uma vez”. Uma vez construído o pipeline, os desenvolvedores não precisarão abrir nenhum arquivo CSS, bastando escrever as classes utilitárias de forma intuitiva nos templates HTML ou Markdown para construir interfaces de usuário complexas em uma velocidade fantástica.

Além disso, como o tamanho do arquivo CSS gerado é sempre minimizado, isso também afeta de forma direta e favorável as métricas de Core Web Vitals, trazendo enormes vantagens do ponto de vista de SEO.

A combinação de Hugo e Tailwind CSS continuará sendo uma das “melhores escolhas” em todos os projetos, desde blogs técnicos pessoais até grandes sites corporativos. Aproveite ao máximo esta poderosa cadeia de ferramentas e tenha uma ótima experiência no desenvolvimento web!

Fundamentos da Arquitetura de Software: O que é a Clean Architecture?

Sat, 12 Sep 2026 12:00:00 +0900

No desenvolvimento de software moderno, construir um “sistema resiliente a mudanças” é um desafio eterno. Mudanças nos requisitos de negócios, surgimento de novos frameworks, renovação da interface de usuário (UI) e migração de banco de dados. Para todas essas mudanças, é exigida uma arquitetura que possa se adaptar flexivelmente sem a necessidade de reconstruir todo o sistema. Uma das respostas para isso é a Clean Architecture (Arquitetura Limpa), proposta por Robert C. Martin (conhecido como Uncle Bob).

Neste artigo, exploraremos a essência da Clean Architecture através de sua história, propósito, detalhes de suas quatro camadas, a Regra de Dependência e exemplos concretos de implementação. Faremos uma explicação técnica muito profunda e detalhada.

1. Os Problemas das Arquiteturas Tradicionais e a História da Clean Architecture

Historicamente, a arquitetura de software passou por várias mudanças de paradigma. Em sistemas iniciais, o código de lógica de negócios, UI e acesso a dados estava fortemente acoplado (o chamado código espaguete). Posteriormente, com o objetivo de separação de conceitos (Separation of Concerns), a arquitetura de três camadas (camada de apresentação, camada de lógica de negócios e camada de acesso a dados) tornou-se popular.

No entanto, a arquitetura de três camadas tradicional tinha um grande problema. Era que o “domínio (lógica de negócios) acabava dependendo do banco de dados ou do framework”.

Por exemplo, se a camada de lógica de negócios chamasse diretamente a camada de acesso a dados (como um ORM), uma mudança no esquema do banco de dados ou no ORM se propagaria para a lógica de negócios. Em outras palavras, surgiu a contradição de que as “regras de negócios”, que são as mais importantes e não deveriam ser alteradas, dependiam da “infraestrutura”, que é onde as mudanças técnicas são mais propensas a ocorrer.

Como solução para isso, as seguintes arquiteturas foram idealizadas:

Arquitetura Hexagonal (Ports and Adapters) - Alistair Cockburn
Onion Architecture (Arquitetura Cebola) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

Todas essas arquiteturas têm o mesmo objetivo. É a “Separação de Conceitos”. O objetivo é dividir o software em camadas, criando um estado em que cada uma é testável independentemente e independente de agentes externos (UI, DB, frameworks).

Robert C. Martin unificou os conceitos dessas excelentes arquiteturas e as resumiu em uma única regra prática, nomeando-a de “Clean Architecture”.

2. Propósitos e Características da Clean Architecture

Sistemas que adotam a Clean Architecture possuem as seguintes características:

Independente de Frameworks (Independent of Frameworks): A arquitetura não depende da existência de bibliotecas de software ricas em recursos. Isso permite que você use frameworks como “ferramentas” em vez de ter que encaixar seu sistema nas restrições deles.
Testável (Testable): As regras de negócios podem ser testadas sem a UI, banco de dados, servidor Web ou qualquer outro elemento externo.
Independente de UI (Independent of UI): A UI pode ser alterada facilmente sem alterar o resto do sistema. Por exemplo, uma UI Web pode ser substituída por uma UI de console sem alterar as regras de negócios.
Independente de Banco de Dados (Independent of Database): Você pode trocar Oracle ou SQL Server por Mongo, BigTable, CouchDB ou qualquer outra coisa. Suas regras de negócios não estão vinculadas ao banco de dados.
Independente de agentes externos (Independent of any external agency): Na verdade, suas regras de negócios simplesmente não sabem nada sobre o mundo exterior.

3. As 4 Camadas da Clean Architecture (Layers)

A Clean Architecture é geralmente representada por um diagrama de círculos concêntricos. Quanto mais próximo do centro, mais o software representa as políticas de alto nível (regras de negócios altamente abstratas). Quanto mais para fora, mais se tornam mecanismos (detalhes concretos).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["UI"]
C["Banco de Dados"]
D["APIs Externas"]
end
subgraph "Interface Adapters"
E["Controladores"]
F["Gateways"]
G["Apresentadores"]
end
subgraph "Application Business Rules (Use Cases)"
H["Interatores de Caso de Uso"]
end
subgraph "Enterprise Business Rules (Entities)"
I["Entidades"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entidades (Entities)

As entidades encapsulam as regras de negócios de toda a empresa (Enterprise Business Rules). Uma entidade pode ser um objeto com métodos ou pode ser um conjunto de estruturas de dados e funções. São as regras mais gerais e de alto nível que podem ser reutilizadas em diversas aplicações diferentes dentro da empresa. Mesmo que você esteja criando apenas uma única aplicação, as entidades são os objetos de negócios dessa aplicação. Elas não são afetadas por nenhuma mudança externa (como mudanças na navegação de página ou mudanças de segurança).

3.2. Casos de Uso (Use Cases)

A camada de casos de uso contém as regras de negócios específicas da aplicação (Application Business Rules). Ela encapsula e implementa todos os casos de uso do sistema. Os casos de uso orquestram o fluxo de dados para e das entidades e orientam essas entidades a usar suas regras de negócios para atingir os objetivos do caso de uso. Mudanças nesta camada não devem afetar as entidades. Além disso, essa camada não é afetada por mudanças externas como banco de dados, UI ou frameworks. Os casos de uso estão completamente isolados dessas preocupações.

3.3. Adaptadores de Interface (Interface Adapters)

A camada de adaptadores de interface é um conjunto de adaptadores que convertem dados do formato mais conveniente para os casos de uso e entidades, para o formato mais conveniente para agentes externos, como o Banco de Dados ou a Web. Por exemplo, é aqui que residem os elementos da arquitetura MVC (Model-View-Controller) de uma GUI no mundo Web. Os controladores recebem a entrada do usuário e a passam para os casos de uso, e os apresentadores recebem a saída dos casos de uso e a formatam para a visualização (UI). Também é função desta camada converter os dados no formato que o banco de dados (como SQL) possa entender. Nenhum código interno a este círculo deve saber nada sobre o banco de dados.

3.4. Frameworks e Drivers (Frameworks & Drivers)

A camada mais externa é geralmente composta de ferramentas como bancos de dados e frameworks da Web. Normalmente, você não escreve muito código nesta camada, a não ser o “código de cola” (glue code) que se comunica com o próximo círculo para dentro. Esta camada contém todos os detalhes. A Web é um detalhe. O banco de dados é um detalhe. Mantemos essas coisas do lado de fora onde elas podem fazer pouco mal.

4. A Regra de Dependência (The Dependency Rule)

Existe uma regra primordial para fazer a Clean Architecture funcionar, e que nunca deve ser quebrada. É a “Regra de Dependência (The Dependency Rule)”.

As dependências do código-fonte devem apontar apenas para dentro, em direção às políticas de nível mais alto.

O código pertencente a um círculo interno não deve saber nada sobre o código de um círculo externo. Nenhum nome declarado em um círculo externo (funções, classes, variáveis, etc.) pode ser mencionado pelo código em um círculo interno. Da mesma forma, formatos de dados usados em um círculo externo não devem ser usados por um círculo interno, especialmente se esses formatos forem gerados por um framework em um círculo externo.

graph LR
A["Frameworks & Drivers"] -->| Depende | B["Interface Adapters"]
B -->| Depende | C["Use Cases"]
C -->| Depende | D["Entities"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

Expressando matematicamente, se definirmos o índice da camada como $L_i$, onde $i=0$ é a Entidade (camada mais interna) e $i=3$ é o Framework (camada mais externa), se houver uma dependência de uma camada $L_m$ para $L_n$, a seguinte inequação deve ser sempre verdadeira:

$$ m > n $$

Ou seja, o vetor de dependência $\vec{D}$ aponta sempre para o centro.

5. Cruzando Fronteiras: Princípio da Inversão de Dependência (DIP)

Ao tentar aderir à Regra de Dependência, você logo enfrentará um grande problema. “O que fazer quando um caso de uso precisa obter dados do banco de dados?”

Se a camada de casos de uso (interna) chamar diretamente a camada de adaptadores de interface (a implementação do Repositório externa), a dependência apontará para fora, violando a Regra de Dependência.

O que resolve esse problema é o “D” dos princípios SOLID (Dependency Inversion Principle: Princípio da Inversão de Dependência).

Definição do Princípio da Inversão de Dependência (DIP)

Módulos de alto nível não devem depender de módulos de baixo nível. Ambos devem depender de abstrações.
Abstrações não devem depender de detalhes. Detalhes devem depender de abstrações.

Para conseguir isso, definimos uma interface (abstração) na camada de caso de uso e a implementamos na camada externa (adaptadores de interface). A camada de caso de uso depende apenas da interface que ela mesma definiu e não depende da implementação concreta externa.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Depends on (Depende de)"
UserRepositoryImpl ..|> UserRepository : "Implements (Implementa)"
note for UseCaseInteractor "Camada Interna (Caso de Uso)"
note for UserRepository "Camada Interna (Caso de Uso)"
note for UserRepositoryImpl "Camada Externa (Adaptadores de Interface)"

Na figura acima, o fluxo de controle (Control Flow) em tempo de execução é UseCaseInteractor $\rightarrow$ UserRepositoryImpl. No entanto, a dependência do código-fonte (Source Code Dependency) é UserRepositoryImpl $\rightarrow$ UserRepository (para dentro). Usando o polimorfismo, fomos capazes de direcionar a dependência do código-fonte na direção oposta ao fluxo de controle. É por isso que é chamado de “Inversão” de dependência.

6. Exemplo Concreto de Implementação em TypeScript

Aqui, mostramos um exemplo simples de implementação da Clean Architecture (funcionalidade de registro de usuário) usando TypeScript.

6.1. Entidades (Entities)

As regras de negócios mais centrais.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // Regra de negócios específica da entidade (ex: verificação do tamanho do nome)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Casos de Uso (Use Cases)

Na camada de caso de uso, definimos as estruturas de dados de entrada e saída (DTO) e a interface do repositório para inverter a dependência.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Interface definida pela camada de caso de uso
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // Depende da abstração (interface). Não depende de implementações concretas.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('O usuário já existe');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Dados de usuário inválidos');
 }

 // Chama o processo externo de salvar no DB, mas a dependência aponta para dentro (interface)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. Adaptadores de Interface (Interface Adapters)

Criamos o processo de acesso concreto ao banco de dados (implementação do Repositório) e o Controlador que processa requisições HTTP.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// Assumindo cliente de DB que é a camada externa (Driver)
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. Componente Principal (Injeção de Dependência: DI)

Ao iniciar a aplicação, todas as dependências são construídas (fiação/wiring). Isso é chamado de Composition Root.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. Inicialização do driver
const dbClient = new DatabaseClient(/* informações de conexão */);

// 2. Inicialização do adaptador (Instancia a classe concreta)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Inicialização do caso de uso (Injeta a implementação concreta na interface = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Inicialização do controlador
const userController = new UserController(registerUserUseCase);

// Roteamento
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('O servidor está rodando na porta 3000');
});

Dessa forma, o “script de inicialização” mais externo assume os detalhes sujos (instanciação de classes concretas) e passa apenas interfaces limpas para as camadas internas. Com essa estrutura, a lógica de negócios fica completamente isolada do mundo exterior.

7. Considerações Matemáticas sobre Acoplamento e Coesão

Na engenharia de software, o Acoplamento (Coupling) e a Coesão (Cohesion) são métricas para avaliar a qualidade de uma arquitetura.

O acoplamento $C$ representa a força da dependência entre módulos. Se o módulo $A$ depende do módulo $B$, e definirmos o número total de dependências do sistema como $N_{dep}$ e o número de módulos como $N_{mod}$, uma das métricas que indica a complexidade pode ser expressa da seguinte forma:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

Na Clean Architecture, ao aplicar o DIP, direcionamos as setas de dependência física para abstrações. A frequência de mudança das abstrações (interfaces) (Instability: $I$) é projetada para ser muito baixa.

A Instability $I$ é calculada pela seguinte fórmula (conforme definido por Robert C. Martin):

$C_e$ (Efferent Coupling): Acoplamento eferente (quantos módulos ele depende)
$C_a$ (Afferent Coupling): Acoplamento aferente (quantos módulos dependem dele)

$$ I = \frac{C_e}{C_e + C_a} $$

Quando $I = 0$, o componente é perfeitamente estável (não depende de ninguém, e os outros dependem dele).
Quando $I = 1$, o componente é perfeitamente instável (ninguém depende dele, e ele depende de outros).

A “Camada de Entidades” da Clean Architecture tem $C_e = 0$ (não depende do exterior), portanto, $I = 0$. Em outras palavras, é a camada mais estável. Por outro lado, as “Camadas de UI” ou “Camadas de DB” têm $C_a \approx 0$ e $C_e > 0$, de forma que $I \approx 1$, tornando-as camadas fáceis de alterar (camadas instáveis).

Um princípio arquitetural importante, o SDP (Stable Dependencies Principle: Princípio das Dependências Estáveis), determina que “dependências devem apontar para os componentes mais estáveis (componentes com $I$ menor)”. Os círculos concêntricos da Clean Architecture são uma visualização exata desse SDP, projetados para que a dependência aponta de fora ($I=1$) para dentro ($I=0$).

8. Estratégia de Testes e Clean Architecture

Um dos maiores benefícios da Clean Architecture é a facilidade de testes. Como as camadas são separadas, você pode escrever testes de forma independente de acordo com cada camada.

8.1. Testes de Entidades (Unit Test)

Por ser puramente lógica sem dependências externas, não são necessários bancos de dados ou mocks. É o teste mais confiável e rápido que você pode executar.

8.2. Testes de Casos de Uso (Unit Test with Mocks)

Todas as dependências externas, como repositórios, são definidas como interfaces, então durante os testes você só precisa injetar (DI) mocks para testes ou implementações em memória (Fake). Não é necessário subir um banco de dados real. Isso permite testar ramificações complexas e tratamento de exceções da lógica de negócios muito rapidamente.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Exemplo de teste de Caso de Uso (Assumindo Jest)
test('Deve resultar em erro ao tentar registrar com um endereço de email existente', async () => {
 // Criação do repositório Fake
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Retorna usuário existente
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Execução do caso de uso e asserção de erro
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('O usuário já existe');
});

8.3. Testes de Adaptadores (Integration Test)

A classe de implementação do repositório se conecta a um banco de dados real e testa se o SQL está correto. O teste do controlador testa a parte que recebe a requisição HTTP e retorna JSON. Aqui, não se faz uma verificação detalhada da lógica de negócios, mas apenas confirma-se se a “conversão” e a “comunicação” estão corretas.

9. Desvantagens da Clean Architecture e Quando Adotar

Embora a Clean Architecture pareça onipotente, ela não é uma bala de prata. Existem as seguintes desvantagens (trade-offs):

Aumento do custo inicial de aprendizado e desenvolvimento: O número de arquivos e interfaces (abstrações) aumenta consideravelmente. Haverá muito “código boilerplate” (código clichê), como o reempacotamento de DTOs.
Exagero para projetos de pequena escala (Overkill): Para um protótipo construído em poucos dias ou ferramentas de uso único que quase nunca sofrerão alterações, adotar essa arquitetura costuma ser um desperdício de esforço. Também não é adequada para APIs simples que realizam apenas operações CRUD.

Quando você deve adotar:

Produtos com expectativa de manutenção e operação de longo prazo (vários anos ou mais).
Sistemas onde as regras de negócios são complexas e mudanças de especificações ocorrem com frequência.
Quando se quer avançar com a divisão de tarefas em grandes equipes de desenvolvimento (frontend, backend, infraestrutura, etc.).
Quando você deseja modelar domínios de negócios complexos combinando com DDD (Domain-Driven Design: Projeto Orientado a Domínio).

10. Conclusão

A Clean Architecture é uma filosofia de design destinada a proteger o núcleo do sistema, as “regras de negócios”, de “detalhes” como UI, banco de dados e frameworks.

No centro disso estão a Regra de Dependência e o Princípio da Inversão de Dependência (DIP). Ao aplicar esses princípios corretamente, o software se torna flexível às mudanças, fácil de testar e capaz de manter seu valor a longo prazo.

O importante não é imitar cegamente a estrutura de diretórios da Clean Architecture, mas entender a essência de “por que dividir dessa forma” e “para onde as setas de dependência estão apontando”, aplicando-a adequadamente de acordo com o tamanho e a complexidade do seu próprio projeto.

Referência: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” by Robert C. Martin

Pontos-chave do Design CSS para Suporte ao Modo Escuro em Blogs

Sat, 12 Sep 2026 12:00:00 +0900

No desenvolvimento web moderno, o suporte ao Modo Escuro (Dark Mode) mudou de ser um mero “recurso interessante de se ter (Nice to have)” para um “requisito essencial (Must have)” a fim de melhorar a experiência do usuário (UX). Especialmente em mídias onde se espera longos períodos de leitura de texto, como blogs e sites de documentação, o suporte ao modo escuro é extremamente importante, pois ajuda a reduzir o cansaço visual do usuário e a economizar o consumo de bateria do dispositivo.

Neste artigo, aprofundaremos as questões técnicas inevitáveis na implementação do modo escuro em um blog e os pontos-chave de um design CSS altamente manutenível, a partir da perspectiva de um engenheiro de frontend. Cobriremos tudo sobre a implementação do modo escuro, incluindo a utilização de CSS Custom Properties (variáveis CSS), controle avançado de JavaScript e integração com SSR para prevenir FOUC (Flash of Unstyled Content), design de cores (RGB, HSL e o mais recente OKLCH) para garantir acessibilidade (WCAG 2.1 AAA), e até exemplos práticos de código usando Tailwind CSS.

1. Fundamentos do Design de Tema com CSS Custom Properties (Variáveis CSS)

Atualmente, a abordagem mais padrão e poderosa para implementar o modo escuro é o uso de CSS Custom Properties (variáveis CSS). Enquanto as variáveis de pré-processadores CSS como Sass ($color) são resolvidas estaticamente durante a compilação, as variáveis CSS são resolvidas e sobrescritas dinamicamente em tempo de execução no navegador. Isso permite que você mude as cores de toda a página instantaneamente, apenas alternando as classes através do JavaScript.

1.1 Definição da Paleta de Cores Básica

Primeiro, definimos a paleta de cores para o modo claro (padrão) usando a pseudoclasse :root. O padrão clássico de design é sobrescrever essas variáveis quando um atributo como [data-theme='dark'] (ou uma classe .dark) é adicionado.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* Definição de variáveis para o modo claro (padrão) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Sobrescrevendo variáveis no modo escuro */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* Aplicação real */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

Desta forma, ao separar completamente as especificações de layout e tipografia das especificações de cores (tema), a manutenibilidade do CSS aumenta drasticamente.

1.2 Utilização do @media (prefers-color-scheme: dark)

Se o modo escuro estiver configurado a nível de sistema operacional (OS), é desejável do ponto de vista da UX aplicar o tema escuro automaticamente desde a primeira visita ao site. Isso é alcançado pela media query @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Fallback caso a configuração do sistema operacional seja modo escuro */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

Nesta sintaxe, as variáveis são sobrescritas respeitando a configuração de modo escuro do OS, a menos que o usuário tenha selecionado explicitamente o modo claro (data-theme='light').

2. Compreendendo Espaços de Cores e Acessibilidade (WCAG 2.1 AAA)

Ao projetar as cores para o modo escuro, simplesmente “tornar o fundo preto e o texto branco” não é suficiente. Se o contraste for muito forte, causará halação e dificultará a leitura, enquanto que se o contraste for muito baixo, a visibilidade será prejudicada. As Diretrizes de Acessibilidade de Conteúdo da Web (WCAG) definem rigorosamente a taxa de contraste para garantir a visibilidade.

2.1 Fórmula de Cálculo da Taxa de Contraste WCAG

A taxa de contraste (Contrast Ratio) $CR$ no WCAG é definida usando a luminância relativa (Relative Luminance) da cor de fundo e da cor do primeiro plano, da seguinte forma:

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

Onde $L_{lighter}$ é a luminância relativa da cor mais clara e $L_{darker}$ é a luminância relativa da cor mais escura (os valores variam de 0.0 a 1.0). Para alcançar o nível AAA do WCAG 2.1, é necessária uma taxa de contraste de 7:1 ou superior para textos normais e 4.5:1 ou superior para textos grandes.

A luminância relativa $L$ é calculada através da seguinte fórmula complexa a partir dos valores RGB no espaço de cor sRGB.

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

Cada componente ($R, G, B$) usa o valor normalizado resultante da divisão do valor original de 8 bits ($R_{sRGB}$) por 255 e passa pela seguinte transformação para desfazer a correção gama:

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

É difícil fazer esse cálculo manualmente, mas usando ferramentas de design de cores, é possível selecionar mecanicamente cores que satisfaçam a taxa de contraste de 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

Antigamente, RGB e HSL eram as opções predominantes ao criar paletas de cores. No entanto, elas possuem grandes falhas do ponto de vista da “uniformidade perceptiva”.

RGB: São as três cores primárias mecânicas da luz, tornando difícil para os humanos ajustarem intuitivamente, como “fazer mais claro” ou “fazer mais escuro”.
HSL: Usa Matiz (Hue), Saturação (Saturation) e Luminosidade (Lightness), mas a “Luminosidade (L)” do HSL não corresponde ao brilho percebido pelo olho humano. Por exemplo, um amarelo puro e um azul puro com 50% de luminosidade no HSL têm o mesmo brilho numericamente, mas para o olho humano, o amarelo parece esmagadoramente mais brilhante.
OKLCH: O espaço de cores mais recente introduzido no CSS Color Module Level 4. Consiste em Lightness (Luminosidade perceptiva), Chroma (Saturação) e Hue (Matiz), e corresponde perfeitamente às características visuais humanas (uniformidade perceptiva).

Usando OKLCH, você pode manter a mesma luminosidade perceptiva (Lightness) mesmo se alterar o matiz (Hue), tornando a geração de paletas de cores para o modo escuro extremamente previsível e segura.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* Exemplo de definição de variáveis CSS usando OKLCH */
:root {
 /* Modo claro com luminosidade base alta e saturação contida */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* No modo escuro, basta inverter a luminosidade, sendo mais fácil manter o contraste perceptivo */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Um pouco mais claro para o modo escuro visando garantir visibilidade */
}

Ao adotar OKLCH desta maneira, você pode construir de forma simples a lógica para garantir uma taxa de contraste consistente (nível WCAG AAA) entre vários temas.

3. Prevenção de FOUC (Flash of Unstyled Content) e Hidratação SSR

O que mais incomoda os desenvolvedores na implementação do modo escuro é o problema da tela piscando, conhecido como FOUC (Flash of Unstyled Content).

3.1 A Armadilha da Mudança de Tema no Lado do Cliente (JS)

Em SPAs como React ou Vue (ou sites estáticos baseados em SSG), a abordagem comum é salvar a configuração do usuário no localStorage, lê-la com JavaScript e então alternar o tema. No entanto, quando esse processo é feito num useEffect do React, ocorrem os seguintes problemas:

O navegador renderiza o HTML/CSS do modo claro.
O bundle do JS é carregado e executado.
Lê a configuração dark do localStorage.
A classe dark é adicionada ao HTML e a tela escurece repentinamente (pisca).

3.2 A Prevenção Perfeita contra FOUC: Utilização de Cookies e SSR

A melhor prática para prevenir completamente o FOUC e evitar erros de hidratação é salvar as configurações de tema do usuário em document.cookie e retornar o HTML com as classes apropriadas anexadas no estágio de Renderização do Lado do Servidor (SSR).

O diagrama de sequência abaixo mostra o fluxo ideal para inicializar o tema usando Cookies.

sequenceDiagram
participant User as "Usuário"
participant Browser as "Navegador OS"
participant Server as "Servidor SSR"
participant DOM as "Client DOM"
User->>Browser: "Solicitar Página"
Browser->>Server: "Requisição GET com Cookie (theme=dark)"
Server-->>Browser: "Retorna HTML com <html data-theme='dark'>"
Browser->>DOM: "Renderiza HTML Inicial (Sem FOUC)"
DOM->>DOM: "Executar Script de Hidratação"
alt "Ausência de Cookie (Primeira Visita)"
DOM->>Browser: "Verificar prefers-color-scheme do OS"
Browser-->>DOM: "Resultado matchMedia (ex: dark)"
DOM->>DOM: "Definir data-theme='dark' via script inline bloqueante"
end

3.3 Linha de Defesa via Scripts Inline (Para sites estáticos que não podem usar Cookies)

No caso de blogs (como Hugo, Gatsby ou exportações estáticas do Astro) baseados apenas em SSG (Geração de Site Estático) onde o SSR é impossível, é essencial colocar um script JavaScript inline dentro da tag <head> para execução bloqueante e anexar a classe antes da renderização do DOM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Colocar no final do <head> -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

Esse pequeno script bloqueia a renderização do navegador e é executado instantaneamente. Como o atributo data-theme já está configurado no momento em que a tela é renderizada, ele previne completamente a cintilação da tela (FOUC).

4. Abordagens de Implementação com Tailwind CSS e SCSS/CSS Puro

Ao incorporar o modo escuro num projeto real, é necessário entender as abordagens de cada ferramenta.

4.1 Modo Escuro no Tailwind CSS

O Tailwind CSS oferece nativamente a variante dark:, tornando a implementação do modo escuro extremamente simples. O atributo darkMode deve ser definido no arquivo de configuração (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (depende do OS) ou 'class' (pode ser alternado manualmente)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Usando variáveis CSS para estender a paleta de cores do Tailwind */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

Do lado do HTML, basta adicionar as classes conforme mostrado abaixo.

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

Porém, escrever dark:bg-xxx em todos os elementos pode causar inchaço nos componentes. Em blogs ou aplicações de grande escala, recomenda-se um design híbrido (design de cores semânticas), onde as variáveis CSS são a base e o Tailwind apenas faz referência a elas.

Abaixo está o diagrama de classes que ilustra a herança das variáveis CSS e a camada de aplicação.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "Aplica Classes de Utilidade"

4.2 Implementação em Raw SCSS/CSS (Uso de Mixin)

Em projetos que não usam Tailwind e utilizam SCSS próprio, você pode usar @mixin para encapsular estilos do modo escuro.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* Definição de SCSS Mixin */
@mixin dark-mode {
 /* Suporta tanto o atributo [data-theme='dark'] quanto a configuração do OS */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Exemplo de uso */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

Embora esse método seja intuitivo, o tamanho do arquivo CSS compilado tende a inflar (já que media queries são duplicadas em cada seletor). Assim, a tendência atual ainda é migrar para um design focado em Variáveis CSS (Custom Properties).

5. Otimização de Imagens (Image) e SVG para o Modo Escuro

Mesmo que o design de cores de textos e fundos seja concluído, imagens e ícones (SVG) posicionados como conteúdo podem parecer extremamente brilhantes e fora de sintonia se permanecerem na configuração de modo claro. A otimização para eles também é indispensável.

5.1 Filtro CSS para Reduzir a Luminosidade da Imagem

Imagens bitmap, como fotografias, às vezes ficam brilhantes demais quando exibidas diretamente no modo escuro. Ao usar a propriedade filter do CSS para reduzir ligeiramente a luminosidade (brightness) e contraste (contrast) da imagem, é possível integrá-la naturalmente à interface do tema escuro.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Reduz brilho e aumenta ligeiramente o contraste */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Retorna ao brilho original ao passar o mouse (se o usuário quiser ver mais detalhes) */
 filter: brightness(1) contrast(1);
}

5.2 Alternando Imagens com a Tag `<picture>`

Imagens de logotipo ou ilustrações (como JPEGs com fundo branco fixo) não podem ser corrigidas apenas com processamento de filtros. Nesses casos, o método correto é usar o elemento HTML <picture> e media queries para alternar para outro arquivo de imagem específico para o modo escuro.

1
2
3
4
5
6


<picture>
 <!-- Exibido para usuários com configuração do OS no modo escuro -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Padrão (modo claro) -->
 <img src="/img/logo-light.png" alt="Logotipo do site">
</picture>

*Nota: Este método não está vinculado à alternância manual (por localStorage, etc.) porque depende exclusivamente da configuração do SO. Se a alternância manual estiver implementada, você deve alterar dinamicamente a propriedade src da imagem via JS, ou alternar a classe CSS com display: none.

5.3 Suporte SVG Icons via `currentColor`

Para SVGs embutidos, como ícones, o mais inteligente a fazer é vincular a cor de preenchimento à cor do texto do elemento pai. Defina currentColor no atributo fill ou stroke do SVG.

1
2
3
4


<!-- O valor da propriedade 'color' do CSS (como var(--text-primary)) é aplicado automaticamente -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

Isso garante que, quando você mudar para o modo escuro e a cor do texto do elemento pai se tornar um tom de branco, o ícone SVG também mudará automaticamente para a mesma cor.

6. Conclusão: Em Direção a um Design de Modo Escuro Sustentável

Para implementar um modo escuro de alta qualidade em blogs e aplicações web, um design CSS que aborde todos os pontos abaixo é indispensável:

Utilizar CSS Custom Properties: Evitar fixar códigos de cores e usar abstração para nomes de variáveis semânticas (ex: --bg-primary).
Adotar o espaço de cores OKLCH: Projetar uma taxa de contraste logicamente acessível (7:1 ou maior) que atenda aos critérios WCAG 2.1 AAA em um espaço de cor perceptualmente uniforme.
Medidas Rigorosas Contra FOUC: Eliminar completamente o piscar da tela no carregamento inicial via integração de SSR e Cookies, ou usando scripts inline de bloqueio no <head>.
Otimização de Mídias e Ativos: Usar recursos como filter: brightness(), currentColor e tags <picture> para harmonizar elementos não textuais com o tema escuro.

Ir além da simples “inversão de cores” com estas atenções detalhadas é a marca de um blog moderno que será amado pelos usuários e fornecerá uma excelente experiência de leitura com menos cansaço visual. Aconselhamos os desenvolvedores que estiverem implementando o modo escuro a consultarem os padrões de design discutidos neste artigo.