Padrões Tailwind CSS (v4 - 2025)
CSS utility-first moderno com configuração nativa em CSS.
1. Arquitetura Tailwind v4
O que Mudou em relação ao v3
| v3 (Legado) | v4 (Atual) |
|---|
tailwind.config.js | Diretiva baseada em CSS @theme |
| Plugin PostCSS | Engine Oxide (10x mais rápido) |
| Modo JIT | Nativo, sempre ativo |
| Sistema de plugins | Recursos nativos em CSS |
Diretiva @apply | Ainda funciona, desencorajado |
Conceitos Principais do v4
| Conceito | Descrição |
|---|
| CSS-first | Configuração em CSS, não em JavaScript |
| Engine Oxide | Compilador em Rust, muito mais rápido |
| Nesting Nativo | Aninhamento CSS sem PostCSS |
| Variáveis CSS | Todos os tokens expostos como vars --* |
2. Configuração Baseada em CSS
Definição de Tema
@theme {
/* Cores - use nomes semânticos */
--color-primary: oklch(0.7 0.15 250);
--color-surface: oklch(0.98 0 0);
--color-surface-dark: oklch(0.15 0 0);
/* Escala de espaçamento */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 2rem;
/* Tipografia */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
Quando Estender vs Sobrescrever
| Ação | Usar Quando |
|---|
| Estender | Adicionar novos valores junto aos padrões |
| Sobrescrever | Substituir escala padrão inteiramente |
| Tokens semânticos | Nomenclatura específica do projeto (primary, surface) |
3. Container Queries (Nativo no v4)
Breakpoint vs Container
| Tipo | Responde A |
|---|
Breakpoint (md:) | Largura do viewport |
Container (@container) | Largura do elemento pai |
Uso de Container Query
| Padrão | Classes |
|---|
| Definir container | @container no pai |
| Breakpoint do container | @sm:, @md:, @lg: nos filhos |
| Containers nomeados | @container/card para especificidade |
Quando Usar
| Cenário | Usar |
|---|
| Layouts em nível de página | Breakpoints de viewport |
| Responsivo em nível de componente | Container queries |
| Componentes reutilizáveis | Container queries (independente do contexto) |
4. Design Responsivo
Sistema de Breakpoints
| Prefixo | Largura Mín. | Alvo |
|---|
| (nenhum) | 0px | Base mobile-first |
sm: | 640px | Celular grande / tablet pequeno |
md: | 768px | Tablet |
lg: | 1024px | Laptop |
xl: | 1280px | Desktop |
2xl: | 1536px | Desktop grande |
Princípio Mobile-First
- Escreva os estilos mobile primeiro (sem prefixo)
- Adicione sobrescritas para telas maiores com prefixos
- Exemplo:
w-full md:w-1/2 lg:w-1/3
5. Modo Escuro
Estratégias de Configuração
| Método | Comportamento | Usar Quando |
|---|
class | Classe .dark alterna | Alternador manual de tema |
media | Segue preferência do sistema | Sem controle do usuário |
selector | Seletor customizado (v4) | Tematização complexa |
Padrão de Modo Escuro
| Elemento | Claro | Escuro |
|---|
| Fundo | bg-white | dark:bg-zinc-900 |
| Texto | text-zinc-900 | dark:text-zinc-100 |
| Bordas | border-zinc-200 | dark:border-zinc-700 |
6. Padrões de Layout Modernos
Padrões Flexbox
| Padrão | Classes |
|---|
| Centralizar (ambos eixos) | flex items-center justify-center |
| Empilhamento vertical | flex flex-col gap-4 |
| Linha horizontal | flex gap-4 |
| Espaço entre | flex justify-between items-center |
| Grid com wrap | flex flex-wrap gap-4 |
Padrões Grid
| Padrão | Classes |
|---|
| Auto-fit responsivo | grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))] |
| Assimétrico (Bento) | grid grid-cols-3 grid-rows-2 com spans |
| Layout com sidebar | grid grid-cols-[auto_1fr] |
Nota: Prefira layouts assimétricos/Bento em vez de grids simétricos de 3 colunas.
7. Sistema de Cores Moderno
OKLCH vs RGB/HSL
| Formato | Vantagem |
|---|
| OKLCH | Perceptualmente uniforme, melhor para design |
| HSL | Matiz/saturação intuitivos |
| RGB | Compatibilidade legada |
Arquitetura de Tokens de Cor
| Camada | Exemplo | Propósito |
|---|
| Primitivo | --blue-500 | Valores de cor brutos |
| Semântico | --color-primary | Nomenclatura por propósito |
| Componente | --button-bg | Específico do componente |
8. Sistema de Tipografia
Padrão de Font Stack
| Tipo | Recomendado |
|---|
| Sans | 'Inter', 'SF Pro', system-ui, sans-serif |
| Mono | 'JetBrains Mono', 'Fira Code', monospace |
| Display | 'Outfit', 'Poppins', sans-serif |
Escala de Tipo
| Classe | Tamanho | Uso |
|---|
text-xs | 0.75rem | Labels, legendas |
text-sm | 0.875rem | Texto secundário |
text-base | 1rem | Texto corpo |
text-lg | 1.125rem | Texto de destaque |
text-xl+ | 1.25rem+ | Títulos |
9. Animação e Transições
Animações Incorporadas
| Classe | Efeito |
|---|
animate-spin | Rotação contínua |
animate-ping | Pulso de atenção |
animate-pulse | Pulso sutil de opacidade |
animate-bounce | Efeito de quique |
Padrões de Transição
| Padrão | Classes |
|---|
| Todas as propriedades | transition-all duration-200 |
| Específico | transition-colors duration-150 |
| Com easing | ease-out ou ease-in-out |
| Efeito hover | hover:scale-105 transition-transform |
10. Extração de Componentes
Quando Extrair
| Sinal | Ação |
|---|
| Mesma combinação de classes 3+ vezes | Extrair componente |
| Variantes de estado complexas | Extrair componente |
| Elemento do design system | Extrair + documentar |
Métodos de Extração
| Método | Usar Quando |
|---|
| Componente React/Vue | Dinâmico, precisa de JS |
| @apply em CSS | Estático, não precisa de JS |
| Design tokens | Valores reutilizáveis |
11. Anti-Padrões
| Não Fazer | Fazer |
|---|
| Valores arbitrários em todo lugar | Usar escala do design system |
!important | Corrigir especificidade corretamente |
style= inline | Usar utilities |
| Duplicar listas longas de classes | Extrair componente |
| Misturar config v3 com v4 | Migrar completamente para CSS-first |
Usar @apply excessivamente | Preferir componentes |
12. Princípios de Performance
| Princípio | Implementação |
|---|
| Purge de não usados | Automático no v4 |
| Evitar dinamismo | Sem classes em template strings |
| Usar Oxide | Padrão no v4, 10x mais rápido |
| Cache de builds | Cache em CI/CD |
Lembre-se: O Tailwind v4 é CSS-first. Adote variáveis CSS, container queries e recursos nativos. O arquivo de config agora é opcional.
Uso com Componentes UI: Para theming e customização dos componentes (shadcn-vue / Reka UI), ver .cursor/skills/ui-components/customization.md.
