Tailwind CSS no desenvolvimento WordPress em 2026
Usar Tailwind CSS num block theme do WordPress exigia antes uma negociação cuidadosa entre duas fontes de verdade concorrentes: o theme.json para o editor e um bundle CSS para o front-end. O WordPress 6.7 e o Tailwind v4 acabaram com essa negociação. O padrão abaixo é o que a WPPoland entrega em produção para clientes na Europa em 2026.
O artigo liga-se à página de serviços de headless WordPress para integrações headless e ao Tech Radar Q4 2026, onde o Tailwind consta como ferramenta de produção estável.
Resumo
- Tailwind v4 com um block theme do WordPress 6.7+ é um padrão de produção estável em 2026.
- O theme.json guarda os tokens globais (paleta, fontes, espaçamentos). O Tailwind trata da composição de utilities.
- O JIT compila para uma única folha de estilos agregada, carregada através de wp_enqueue_style e add_editor_style.
- A paridade do editor não é negociável. Os editores têm de ver as mesmas cores, fontes e layouts que o front-end apresenta.
- Evite arbitrary values no markup dos blocos, para que a pré-visualização do editor se mantenha determinística.
Porquê Tailwind CSS num block theme do WordPress
Os block themes e o Tailwind não são sistemas concorrentes; cobrem camadas diferentes. O theme.json define o que os blocos podem escolher: uma paleta de cores com nome, uma escala tipográfica, uma escala de espaçamentos, uma largura de layout. O Tailwind define como essas escolhas se combinam em classes utility que o programador escreve nos templates e no markup dos blocos.
A vantagem face a um block theme puro é a composição de utilities sem escrever novos ficheiros CSS para cada bloco. A vantagem face ao CSS tradicional é a eliminação de código morto graças ao JIT e ao Oxide: um block theme acumula CSS a cada atualização de plugins e do tema, enquanto o resultado do Tailwind se limita ao que os templates e os estilos do editor usam de facto.
A vantagem face ao Tailwind num front-end sem WordPress é a paridade do editor. O editor de blocos tem de renderizar com os mesmos estilos do front-end, caso contrário os editores desenham num universo e publicam noutro.
Como configurar o Tailwind CSS num tema WordPress
O padrão fiável que sobreviveu a três grandes atualizações do WordPress:
Pipeline de build. Vite, esbuild ou @wordpress/scripts (que já encapsula o webpack e o PostCSS) compila o Tailwind v4 a partir de um único ficheiro CSS de entrada. O resultado é uma folha de estilos agregada, com hash para cache busting.
Ordem do enqueue. O Tailwind v4 escreve o seu resultado em camadas da cascata (theme, base, components, utilities), como mostra a documentação do Preflight. A folha de estilos block-library do WordPress não usa camadas: no WordPress 7.0, o ficheiro wp-includes/css/dist/block-library/style.css não contém nenhuma regra @layer. Segundo a MDN, os estilos fora de uma camada ganham sempre aos estilos dentro de uma camada. Carregar o bundle no fim do wp_head não chega, portanto, para que uma utility vença um estilo do core: a ordem só decide entre folhas de estilos sem camadas. A secção sobre camadas, mais abaixo, explica como resolver esses conflitos.
Estilos do editor. O mesmo bundle passa por add_editor_style, para que o Gutenberg renderize da mesma forma. Onde o canvas do editor precisar de outro layout (por exemplo, larguras limitadas), use um pequeno ficheiro CSS só para o editor, aplicado por cima do bundle partilhado.
theme.json. Defina a paleta de cores, as fontes, os espaçamentos e a largura do layout como tokens com nome. Desde a v4, a configuração do Tailwind vive em CSS e não em JavaScript (anúncio do Tailwind CSS v4.0), por isso a associação entre os tokens do theme.json e as utilities escreve-se diretamente no ficheiro CSS de entrada, sem um script intermédio. Uma fonte de verdade, dois consumidores.
Como ligar o theme.json ao @theme no Tailwind v4
O WordPress converte cada preset do theme.json numa propriedade CSS personalizada com o padrão --wp--preset--{tipo}--{slug}. Uma cor com o slug ocean passa a --wp--preset--color--ocean e uma família tipográfica com o slug primary passa a --wp--preset--font-family--primary (Theme Handbook: cores e tipografia). O Tailwind v4, por seu lado, cria utilities a partir das variáveis declaradas em @theme: --color-ocean produz bg-ocean, text-ocean e fill-ocean (variáveis de tema).
Resta ligar os dois lados. Primeiro o theme.json, na versão 3 do esquema:
{
"version": 3,
"settings": {
"color": {
"defaultPalette": false,
"custom": false,
"palette": [
{ "slug": "ocean", "color": "#0b5d7a", "name": "Ocean" },
{ "slug": "charcoal", "color": "#1d2327", "name": "Charcoal" }
]
},
"typography": {
"fontFamilies": [
{ "slug": "primary", "name": "Primary", "fontFamily": "Charter, Cambria, serif" }
]
}
}
}Depois o ficheiro CSS de entrada do tema:
@import "tailwindcss";
@theme inline {
--color-*: initial;
--color-ocean: var(--wp--preset--color--ocean);
--color-charcoal: var(--wp--preset--color--charcoal);
--font-primary: var(--wp--preset--font-family--primary);
}Cada detalhe destes dois blocos vem da documentação. inline é necessário porque a variável do Tailwind aponta para outra variável: sem ele, a utility pode resolver-se para um valor inesperado devido à forma como o CSS resolve var(), e com ele a classe recebe diretamente var(--wp--preset--color--ocean). --color-*: initial remove a paleta predefinida do Tailwind, por isso bg-emerald-500 deixa de existir e ficam apenas as cores do theme.json. No theme.json, defaultPalette: false esconde as cores do core e custom: false limita os utilizadores às cores predefinidas.
O resultado é que o editor que escolhe “Ocean” no seletor de cor e o programador que escreve bg-ocean obtêm o mesmo valor, porque ambos leem a mesma variável. Alterar a cor no theme.json altera também a utility, sem recompilar o Tailwind, porque a classe contém apenas a referência var().
A mesma página da documentação dá duas regras fáceis de ignorar num tema. As variáveis de @theme têm de ser declaradas no nível superior do ficheiro, nunca dentro de um seletor nem de uma media query. As variáveis que não devem gerar utilities (por exemplo, a altura de um cabeçalho fixo usada apenas no CSS de um bloco) declaram-se em :root, não em @theme.
Os espaçamentos funcionam de outra forma. O Tailwind v4 calcula a sua escala a partir de uma única variável --spacing (0.25rem por predefinição), enquanto o WordPress gera um preset por passo, como --wp--preset--spacing--50 (espaçamentos no Theme Handbook). Para as margens e os preenchimentos que os editores podem alterar, use as variáveis do WordPress diretamente no CSS do bloco; deixe a escala do Tailwind para o layout interno dos templates.
Classes Tailwind no markup dos blocos Gutenberg
Três regras pragmáticas para markup de blocos com Tailwind.
Use classes utility para composições pontuais. No template de um bloco hero, a linha class="flex items-center gap-6 px-6 py-12" é mais clara do que uma classe CSS própria.
Use classes com nome para padrões repetidos ao nível do bloco. Um padrão “card” que aparece em vários blocos merece uma classe com nome, composta a partir de utilities com @apply e guardada num pequeno ficheiro CSS do bloco. A classe com nome aparece no inspector do editor e pode ser reutilizada.
Evite arbitrary values no markup. class="mt-[37px]" funciona no front-end, mas gera ruído no editor, onde os blocos esperam tokens de espaçamento previsíveis. Defina o token no theme.json ou alargue a escala no bloco @theme do ficheiro CSS de entrada.
No inspector do editor, registe block styles próprios com nomes alinhados com a intenção das utilities Tailwind. Os editores escolhem “Card large”, os programadores veem block-card-large, e a classe é composta por utilities Tailwind. Editor e código mantêm-se alinhados.
Que ficheiros de um tema WordPress o Tailwind v4 analisa
O Tailwind v4 deteta as classes sem configuração: trata cada ficheiro como texto simples, procura tokens que possam ser classes e descarta os que não correspondem a nenhuma utility (deteção de classes nos ficheiros de origem). Num block theme isso inclui os templates HTML em templates/ e parts/, os padrões PHP em patterns/ e os ficheiros render.php dos blocos. Ficam de fora os ficheiros listados no .gitignore, o node_modules, os ficheiros binários, os ficheiros CSS e os lockfiles dos gestores de pacotes.
Daqui resultam três consequências práticas no WordPress:
As classes guardadas na base de dados não existem para o Tailwind. As classes que um editor acrescenta a um bloco no editor, ou as que chegam com um padrão inserido num artigo, vivem em post_content, não nos ficheiros do tema. O Tailwind não as vê e não gera o respetivo CSS. Se a equipa editorial tiver de usar um conjunto fixo de classes, registe-o com @source inline(), que suporta expansão de chavetas:
@import "tailwindcss";
@source inline("{md:,}grid-cols-{2,3,4}");Os nomes de classes construídos em PHP não são gerados. O Tailwind não interpreta concatenações: 'text-' . $color . '-600' não deixa no ficheiro nenhum nome de classe completo. Escreva a classe completa em cada ramo da condição, como a documentação recomenda para qualquer linguagem de templates.
Os caminhos fora do tema têm de ser declarados. Se os blocos estiverem num plugin próprio, registe-o com @source "../../plugins/blocos-do-site";. Se a pasta vendor/ do Composer não estiver no .gitignore, @source not "../vendor"; evita que o Tailwind percorra milhares de ficheiros PHP de terceiros em cada build.
Porque é que os estilos de blocos do WordPress ganham às utilities do Tailwind
O Tailwind v4 coloca o seu resultado em quatro camadas declaradas por esta ordem: theme, base, components e utilities (Preflight). A regra da cascata que decide está na MDN: as declarações normais fora de uma camada ganham sempre às declaradas dentro de camadas, e entre declarações !important a ordem inverte-se. O WordPress não usa camadas. Além disso, no WordPress 7.0 as classes de presets como .has-ocean-color levam !important no CSS gerado pela classe WP_Theme_JSON, por isso uma cor escolhida no editor impõe-se a qualquer utility de cor sem !important.
Para o trabalho diário resultam duas regras. As utilities funcionam sem atrito nas propriedades que o core não define. Quando o core define uma propriedade, altere o valor na secção styles do theme.json, para que o editor e o front-end mostrem o mesmo, em vez de lutar contra a cascata a partir do markup.
O Preflight merece uma revisão à parte. Também vive na camada base, mas atua sobre o conteúdo que os editores escrevem: remove as margens de todos os elementos, deixa os títulos com o tamanho e o peso do texto normal, retira os marcadores e os números das listas e converte as imagens em display: block. Onde nem o theme.json nem o core definem esses valores, o conteúdo dos artigos perde a formatação. Se o tema já define os estilos base no theme.json, pode importar o Tailwind sem o Preflight:
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);Tamanho do CSS do Tailwind e desempenho do WordPress
Num build de produção típico com WordPress 6.7+ e Tailwind v4 para um site de cliente da WPPoland com muito conteúdo:
- Um único ficheiro CSS agregado. O Tailwind remove as classes não usadas no build de produção e, segundo a página principal do Tailwind, a maioria dos projetos com Tailwind envia menos de 10 kB de CSS ao cliente. Meça o seu próprio bundle depois da compressão.
- O Largest Contentful Paint costuma melhorar no front-end em relação ao CSS acumulado anterior de tema e plugins, porque o bundle é mais pequeno e não há uma cadeia de overrides em cascata para resolver.
- O lado do editor continua rápido, porque o bundle do editor é o mesmo do front-end; não existe uma compilação Tailwind separada só para o editor.
O Tailwind também documenta a velocidade do build. Segundo o anúncio da v4.0, nos projetos da própria equipa os rebuilds completos são mais de 3,5 vezes mais rápidos e os incrementais mais de 8 vezes mais rápidos do que na v3. Isso encurta o ciclo de build e do modo watch do tema. O tamanho final do CSS depende das classes que aparecem nos templates, não do motor.
Erros mais comuns com Tailwind CSS no WordPress
Cinco armadilhas recorrentes em projetos de produção:
add_editor_style esquecido. O front-end renderiza corretamente, o editor aparece sem estilos. Os editores reportam no primeiro dia. Carregue sempre o mesmo bundle do Tailwind no editor.
Paleta codificada fora do theme.json. A utility Tailwind bg-emerald-500 fora do theme.json significa que o seletor de cores do editor de blocos continua a mostrar a paleta antiga. Defina a paleta no theme.json e depois associe-a como tokens Tailwind.
CSS de plugins a sobrepor-se ao Tailwind. Alguns plugins antigos carregam tarde e, como o seu CSS não está numa camada, ganha a qualquer utility do Tailwind independentemente da ordem. :where() não aumenta a especificidade: segundo a MDN, a sua especificidade é sempre zero, e o WordPress usa-o precisamente para limitar a especificidade dos estilos globais (:root :where(...)). Escreva a correção como CSS sem camada num ficheiro próprio do tema, carregado depois do plugin, com um seletor um pouco mais específico do que o do plugin.
Arbitrary spacing no markup. Como referido acima, arruína a experiência no editor. Mantenha-se na escala de espaçamentos.
Tutoriais de Tailwind v3 aplicados à v4. O Tailwind CSS v4.0 estável foi lançado a 22 de janeiro de 2025 (anúncio oficial). Muitos tutoriais de WordPress continuam a mostrar tailwind.config.js e as diretivas @tailwind; na v4 basta @import "tailwindcss" e a configuração vai para @theme. Misturar os dois estilos no mesmo tema produz um build que a equipa deixa de perceber ao fim de alguns meses.
Que browsers o Tailwind v4 suporta num site WordPress
A funcionalidade central do Tailwind CSS v4.0 depende do Chrome 111 e do Safari 16.4 (ambos de março de 2023) e do Firefox 128 (julho de 2024), segundo a página de compatibilidade. O framework assenta em camadas da cascata, propriedades registadas com @property e color-mix() (anúncio da v4.0). Antes de migrar um tema da v3 para a v4, verifique nas estatísticas do site que parte do tráfego chega com browsers anteriores a essas versões.
A mesma página aponta mais dois limites. Algumas utilities usam funcionalidades com suporte limitado, como field-sizing: content, @starting-style ou text-wrap: balance; se os browsers do seu público não as suportam, não as use. E a v4 não foi pensada para ser combinada com Sass, Less ou Stylus, porque o próprio Tailwind faz o papel de pré-processador. Um tema antigo com style.scss tem de passar as suas variáveis para @theme e para CSS nativo antes de compilar com o Tailwind v4.
Tailwind CSS em headless WordPress
Quando o Astro 5 ou o Next.js 15 substitui o front-end do WordPress (veja os serviços de headless WordPress), a configuração do Tailwind passa para o repositório do front-end. O theme.json continua a orientar a experiência do editor para quem escreve conteúdos. O front-end headless importa os mesmos nomes de tokens e associa-os localmente às utilities Tailwind. Dois repositórios, uma fonte de verdade do lado do WordPress.
Para agências que continuam a gerir WordPress monolítico, o padrão deste artigo chega. Para clientes que estão a passar para headless, sirva-se dele como ponto de partida e da página de serviços de headless WordPress para o resto da arquitetura.
Leituras relacionadas
- Serviço de headless WordPress
- Serviço de programador Astro
- Cloudflare Workers e WordPress no edge
- Tech Radar Q4 2026: veredictos sobre o stack
Na implementação, enquadramos este tema em GEO e LLMO.
