Tailwind CSS v4
Este skill cobre o Tailwind CSS v4.x conforme documentado em https://tailwindcss.com/docs. O v4 é configurado em CSS, não em JavaScript, e muitos nomes de classe e padrões do v3 mudaram. O skill contém o que difere do hábito: a configuração CSS-first, padrões surpreendentes, utilitários renomeados e os padrões que a documentação recomenda. Cada afirmação nos arquivos de referência termina com a página de onde veio.
Como navegar
- Leia as regras abaixo. Elas capturam os hábitos do v3 mais frequentes que quebram no v4.
- Abra o arquivo de referência que corresponde à tarefa, na tabela no final.
- Quando o projeto tiver um
tailwind.config.js, diretivas@tailwindou nomes de classe do v3, ou ao revisar código que possa conter hábitos do v3, leiareferences/upgrade-from-v3.mdprimeiro. O caminho de migração padrão énpx @tailwindcss/upgradeem um novo branch, seguido de uma revisão do diff e um teste no navegador. https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool
Início rápido (CSS-first, Vite)
npm install tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })
/* app.css */
@import "tailwindcss";
@theme {
--color-midnight: #121063;
--font-display: "Oswald", sans-serif;
}
@custom-variant dark (&:where(.dark, .dark *));
- Toda a configuração é um pacote, um plugin e um
@import "tailwindcss";. As etapas de instalação não usamtailwind.config.jse nem arraycontent. https://tailwindcss.com/docs/installation/using-vite - O Tailwind escaneia os arquivos fonte por conta própria. Arquivos em
.gitignore,node_modules, arquivos CSS e arquivos de lock são ignorados. https://tailwindcss.com/docs/detecting-classes-in-source-files#which-files-are-scanned - Next.js, Angular e outros bundlers não-Vite usam o plugin PostCSS:
npm install tailwindcss @tailwindcss/postcss postcss, depoisplugins: { "@tailwindcss/postcss": {} }. https://tailwindcss.com/docs/installation/using-postcss - Um
@importde URL de fonte (Google Fonts e similares) vem primeiro, acima de@import "tailwindcss", então a família é declarada em@theme. https://tailwindcss.com/docs/font-family#customizing-your-theme - Variáveis
@themecriam utilitários:--color-midnightgerabg-midnight,text-midnight,fill-midnight, e--font-displaygerafont-display. https://tailwindcss.com/docs/theme#what-are-theme-variables
As regras mais importantes
Configuração e setup
- O plugin PostCSS é
@tailwindcss/postcss, nãotailwindcss. Não adicioneautoprefixeroupostcss-import: imports e prefixos de vendor são embutidos. https://tailwindcss.com/docs/upgrade-guide#using-postcss - Em uma configuração Vite, os guias de framework listam
tailwindcss()primeiro emplugins, antes do plugin do framework (React Router, SvelteKit, SolidJS, Qwik). A documentação não especifica ordem obrigatória. https://tailwindcss.com/docs/installation/framework-guides/react-router https://tailwindcss.com/docs/installation/framework-guides/sveltekit - Personalize em CSS com
@theme. Uma configuração JS não é mais detectada e carrega apenas através de@config "../../tailwind.config.js";, semcorePlugins,safelistouseparator. https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file - Safelist com
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");. https://tailwindcss.com/docs/detecting-classes-in-source-files#safelisting-specific-utilities - Uma biblioteca construída com Tailwind dentro de
node_modulesnão é escaneada: adicione@source "../node_modules/@acmecorp/ui-lib";(caminho relativo à folha de estilo). https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources - Nunca construa nomes de classe dinamicamente (
`bg-${color}-600`). Mapeie valores para strings de classe completas. https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names - Um bloco
<style>do Vue, Svelte ou Astro e um módulo CSS são compilados separadamente. Antes de@applylá, adicione@reference "../app.css";, ou usevar(--color-blue-500)em vez disso. https://tailwindcss.com/docs/compatibility#explicit-context-sharing https://tailwindcss.com/docs/compatibility#vue-svelte-and-astro - Tailwind v4 não foi projetado para ser usado com pré-processadores CSS como Sass, Less ou Stylus, portanto eles não podem ser usados para folhas de estilo ou blocos
<style>em Vue, Svelte ou Astro. https://tailwindcss.com/docs/compatibility#sass-less-and-stylus - v4 requer Safari 16.4+, Chrome 111+, Firefox 128+. Permaneça no v3.4 para navegadores mais antigos. https://tailwindcss.com/docs/upgrade-guide#browser-requirements
Tema e CSS personalizado
- Quando uma variável de tema referencia outra variável, escreva
@theme inline { --font-sans: var(--font-inter); }, caso contrário o valor resolve onde--font-sansé definido. https://tailwindcss.com/docs/theme#referencing-other-variables - Remova um namespace padrão com
--color-*: initial;, o tema inteiro com--*: initial;. https://tailwindcss.com/docs/theme#overriding-the-default-theme - Declare utilitários personalizados com
@utility name { ... }, não@layer utilities, para que variantes funcionem neles. https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities - Leia valores do tema em CSS personalizado e JS como variáveis CSS (
var(--color-red-500)), não comtheme(colors.red.500)ouresolveConfig. https://tailwindcss.com/docs/upgrade-guide#theme-values-in-javascript - Use a mesma unidade para cada breakpoint (rem como os padrões), ou breakpoints se sobrescreverão. https://tailwindcss.com/docs/responsive-design#customizing-your-theme
Sintaxe de classe
- Abreviação de variável CSS usa parênteses:
bg-(--brand-color), nãobg-[--brand-color]. https://tailwindcss.com/docs/upgrade-guide#variables-in-arbitrary-values text-(--my-var)é ambíguo (tamanho da fonte ou cor), então adicione uma dica de tipo:text-(length:--my-var)outext-(color:--my-var). As mesmas dicas existem emfont-(family-name:--f),border-(length:--w),bg-(image:--img)eshadow-(color:--c). https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities https://tailwindcss.com/docs/font-family https://tailwindcss.com/docs/border-width https://tailwindcss.com/docs/background-image https://tailwindcss.com/docs/box-shadow- O modificador important vai no final:
bg-red-500!. https://tailwindcss.com/docs/upgrade-guide#the-important-modifier - Variantes empilhadas aplicam da esquerda para a direita:
*:first:pt-0, nãofirst:*:pt-0. https://tailwindcss.com/docs/upgrade-guide#variant-stacking-order - Classes sem prefixo miram todos os tamanhos.
sm:não significa mobile: escrevatext-center sm:text-left. https://tailwindcss.com/docs/responsive-design#targeting-mobile-screens hover:só se aplica em dispositivos que podem fazer hover (@media (hover: hover)). Trate hover como um aprimoramento. https://tailwindcss.com/docs/upgrade-guide#hover-styles-on-mobile
Padrões alterados
- Cores de borda e divide padrão são
currentColor: sempre defina uma cor comborder. https://tailwindcss.com/docs/upgrade-guide#default-border-color ringé 1pxcurrentColor. Escrevaring-3 ring-blue-500para o visual do v3. https://tailwindcss.com/docs/upgrade-guide#default-ring-width-and-color- Oculte outlines de foco com
outline-hidden(mantido em modo forced-colors): v3focus:outline-nonevirafocus:outline-hidden.outline-noneagora remove o outline completamente. https://tailwindcss.com/docs/upgrade-guide#renamed-outline-utility - As escalas mudaram: v3
shadow-sm,rounded-sm,blur-smagora são-xs, e v3shadow,rounded,blurpuros agora são-sm. https://tailwindcss.com/docs/upgrade-guide#updated-shadow-radius-and-blur-scales - Gradientes são
bg-linear-to-r, maisbg-radialebg-conic-<angulo>. https://tailwindcss.com/docs/background-image#adding-a-linear-gradient containernão centraliza nem adiciona padding: escrevacontainer mx-auto px-4. https://tailwindcss.com/docs/max-width#using-breakpoints-container- Para grids, layout de wrapping ou filhos em ordem personalizada, use
gapem vez despace-x-*espace-y-*. https://tailwindcss.com/docs/margin#limitations - Botões têm
cursor: default. https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor - Placeholders usam a cor de texto atual com 50% de opacidade. https://tailwindcss.com/docs/upgrade-guide#new-default-placeholder-color
- Classes de display não mais sobrescrevem o atributo
hidden: removahiddenpara mostrar o elemento. https://tailwindcss.com/docs/upgrade-guide#hidden-attribute-takes-priority
Modo escuro com uma classe
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
// inline em <head>, antes da página renderizar
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
Defina localStorage.theme = "dark" ou "light", e localStorage.removeItem("theme") para seguir o sistema. https://tailwindcss.com/docs/dark-mode#with-system-theme-support
Arquivos de referência
| Arquivo | Leia quando |
|---|---|
| references/installation-and-frameworks.md | Instalando Tailwind, escolhendo Vite, PostCSS ou CLI, passos específicos de framework, módulos CSS, ferramentas de editor |
| references/upgrade-from-v3.md | Migrando um projeto v3, revisando código com nomes de classe ou configuração v3 |
| references/utilities-and-variants.md | Escrevendo classes: valores arbitrários, conflitos, variantes de estado, group e peer, responsivo, container queries, modo escuro |
| references/theme-and-colors.md | Adicionando ou sobrescrevendo cores, fontes, breakpoints, espaçamento, animações, namespaces de tema |
| references/custom-styles.md | Estilos base, Preflight, classes de componente, @utility, utilitários funcionais, @custom-variant, @variant |
| references/directives-and-source-detection.md | @apply, @reference, --alpha(), --spacing(), @config, @plugin, @source, opções de import (prefix, important, source) |
| references/layout-flexbox-grid.md | Display, position, inset, z-index, columns, flex, grid, alinhamento e alinhamento -safe |
| references/spacing-and-sizing.md | Padding, margin, space, width, height, size, container scale, unidades de viewport, tamanhos lógicos |
| references/typography.md | Fontes, tamanho da fonte e altura da linha, letter-spacing, text wrap, overflow wrap, decoração, content |
| references/backgrounds-and-borders.md | Gradientes, background image, tamanho e posição, raio, largura e cor da borda, outlines |
| references/effects-and-filters.md | Sombras, rings, sombra em texto, opacidade, modos de mesclagem, máscaras, filtros e backdrop filters |
| references/transitions-transforms-tables.md | Transições, transições discretas, animações, rotacionar, escalar, transladar, 3D, zoom, tabelas |
| references/interactivity-and-svg.md | Esquema de cores, field sizing, scrollbars, scroll snap, cursor, will-change, fill e stroke de SVG, forced colors |