1---2name: tailwind-patterns3description: Princípios do Tailwind CSS v4. Configuração baseada em CSS, container queries, padrões modernos, arquitetura de design tokens.4---56# Padrões Tailwind CSS (v4 - 2025)78> Utility-first CSS moderno com configuração nativa de CSS.910---1112## 1. Arquitetura Tailwind v41314### O que Mudou da v31516| v3 (Legado) | v4 (Atual) |17|-------------|-----------|18| `tailwind.config.js` | Diretiva `@theme` baseada em CSS |19| Plugin PostCSS | Oxide engine (10x mais rápido) |20| Modo JIT | Nativo, sempre ativo |21| Sistema de plugins | Recursos nativos de CSS |22| Diretiva `@apply` | Ainda funciona, desaconselhado |2324### Conceitos Principais v42526| Conceito | Descrição |27|----------|-----------|28| **CSS-first** | Configuração em CSS, não JavaScript |29| **Oxide Engine** | Compilador baseado em Rust, muito mais rápido |30| **Nesting Nativo** | Nesting de CSS sem PostCSS |31| **Variáveis CSS** | Todos os tokens expostos como variáveis `--*` |3233---3435## 2. Configuração Baseada em CSS3637### Definição de Tema3839```40@theme {41 /* Cores - use nomes semânticos */42 --color-primary: oklch(0.7 0.15 250);43 --color-surface: oklch(0.98 0 0);44 --color-surface-dark: oklch(0.15 0 0);45 46 /* Escala de espaçamento */47 --spacing-xs: 0.25rem;48 --spacing-sm: 0.5rem;49 --spacing-md: 1rem;50 --spacing-lg: 2rem;51 52 /* Tipografia */53 --font-sans: 'Inter', system-ui, sans-serif;54 --font-mono: 'JetBrains Mono', monospace;55}56```5758### Quando Estender vs Sobrescrever5960| Ação | Use Quando |61|------|-----------|62| **Estender** | Adicionar novos valores junto aos padrões |63| **Sobrescrever** | Substituir escala padrão completamente |64| **Tokens semânticos** | Nomenclatura específica do projeto (primary, surface) |6566---6768## 3. Container Queries (Nativo v4)6970### Breakpoint vs Container7172| Tipo | Responde A |73|------|-----------|74| **Breakpoint** (`md:`) | Largura do viewport |75| **Container** (`@container`) | Largura do elemento pai |7677### Uso de Container Query7879| Padrão | Classes |80|--------|---------|81| Definir container | `@container` no pai |82| Breakpoint de container | `@sm:`, `@md:`, `@lg:` nos filhos |83| Containers nomeados | `@container/card` para especificidade |8485### Quando Usar8687| Cenário | Use |88|--------|-----|89| Layouts no nível da página | Breakpoints de viewport |90| Design responsivo no nível de componente | Container queries |91| Componentes reutilizáveis | Container queries (independentes de contexto) |9293---9495## 4. Design Responsivo9697### Sistema de Breakpoints9899| Prefixo | Largura Mínima | Alvo |100|---------|---|---|101| (nenhum) | 0px | Base mobile-first |102| `sm:` | 640px | Telefone grande / tablet pequeno |103| `md:` | 768px | Tablet |104| `lg:` | 1024px | Laptop |105| `xl:` | 1280px | Desktop |106| `2xl:` | 1536px | Desktop grande |107108### Princípio Mobile-First1091101. Escreva estilos mobile primeiro (sem prefixo)1112. Adicione substituições para telas maiores com prefixos1123. Exemplo: `w-full md:w-1/2 lg:w-1/3`113114---115116## 5. Modo Escuro117118### Estratégias de Configuração119120| Método | Comportamento | Use Quando |121|--------|---|---|122| `class` | Classe `.dark` ativa | Alternador de tema manual |123| `media` | Segue preferência do sistema | Sem controle do usuário |124| `selector` | Seletor customizado (v4) | Temas complexos |125126### Padrão de Modo Escuro127128| Elemento | Claro | Escuro |129|----------|-------|--------|130| Fundo | `bg-white` | `dark:bg-zinc-900` |131| Texto | `text-zinc-900` | `dark:text-zinc-100` |132| Bordas | `border-zinc-200` | `dark:border-zinc-700` |133134---135136## 6. Padrões de Layout Moderno137138### Padrões Flexbox139140| Padrão | Classes |141|--------|---------|142| Centrar (ambos os eixos) | `flex items-center justify-center` |143| Stack vertical | `flex flex-col gap-4` |144| Linha horizontal | `flex gap-4` |145| Espaçamento entre | `flex justify-between items-center` |146| Grade com wrap | `flex flex-wrap gap-4` |147148### Padrões Grid149150| Padrão | Classes |151|--------|---------|152| Auto-fit responsivo | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |153| Assimétrico (Bento) | `grid grid-cols-3 grid-rows-2` com spans |154| Layout sidebar | `grid grid-cols-[auto_1fr]` |155156> **Nota:** Prefira layouts assimétricos/Bento em vez de grids simétricos de 3 colunas.157158---159160## 7. Sistema de Cores Moderno161162### OKLCH vs RGB/HSL163164| Formato | Vantagem |165|---------|----------|166| **OKLCH** | Perceptualmente uniforme, melhor para design |167| **HSL** | Matiz/saturação intuitivos |168| **RGB** | Compatibilidade legada |169170### Arquitetura de Token de Cor171172| Camada | Exemplo | Propósito |173|--------|---------|-----------|174| **Primitiva** | `--blue-500` | Valores de cor brutos |175| **Semântica** | `--color-primary` | Nomenclatura baseada em propósito |176| **Componente** | `--button-bg` | Específico do componente |177178---179180## 8. Sistema de Tipografia181182### Padrão de Pilha de Fontes183184| Tipo | Recomendado |185|------|-------------|186| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |187| Mono | `'JetBrains Mono', 'Fira Code', monospace` |188| Display | `'Outfit', 'Poppins', sans-serif` |189190### Escala de Tipos191192| Classe | Tamanho | Uso |193|--------|---------|-----|194| `text-xs` | 0.75rem | Labels, captions |195| `text-sm` | 0.875rem | Texto secundário |196| `text-base` | 1rem | Texto do corpo |197| `text-lg` | 1.125rem | Texto destaque |198| `text-xl`+ | 1.25rem+ | Headings |199200---201202## 9. Animações e Transições203204### Animações Nativas205206| Classe | Efeito |207|--------|--------|208| `animate-spin` | Rotação contínua |209| `animate-ping` | Pulso de atenção |210| `animate-pulse` | Pulso sutil de opacidade |211| `animate-bounce` | Efeito de salto |212213### Padrões de Transição214215| Padrão | Classes |216|--------|---------|217| Todas as propriedades | `transition-all duration-200` |218| Específica | `transition-colors duration-150` |219| Com easing | `ease-out` ou `ease-in-out` |220| Efeito hover | `hover:scale-105 transition-transform` |221222---223224## 10. Extração de Componentes225226### Quando Extrair227228| Sinal | Ação |229|-------|------|230| Mesma combinação de classes 3+ vezes | Extrair componente |231| Variantes de estado complexas | Extrair componente |232| Elemento do design system | Extrair + documentar |233234### Métodos de Extração235236| Método | Use Quando |237|--------|-----------|238| **Componente React/Vue** | Dinâmico, JS necessário |239| **`@apply` em CSS** | Estático, JS não necessário |240| **Design tokens** | Valores reutilizáveis |241242---243244## 11. Anti-padrões245246| Não Faça | Faça |247|----------|------|248| Valores arbitrários em toda parte | Use escala de design system |249| `!important` | Corrija especificidade propriamente |250| `style=` inline | Use utilities |251| Duplicar listas longas de classes | Extraia componente |252| Misturar config v3 com v4 | Migre completamente para CSS-first |253| Usar `@apply` pesadamente | Prefira componentes |254255---256257## 12. Princípios de Performance258259| Princípio | Implementação |260|-----------|---|261| **Purge unused** | Automático em v4 |262| **Evite dinamismo** | Sem classes com template string |263| **Use Oxide** | Padrão em v4, 10x mais rápido |264| **Cache builds** | CI/CD caching |265266---267268> **Lembre-se:** Tailwind v4 é CSS-first. Abraça variáveis CSS, container queries e recursos nativos. O arquivo de config agora é opcional.
artubss