Migrar para Tailwind 4 como trabalho próprio (com prova visual), não como bump de dependência

[melgarafael]

O Dependabot propôs tailwindcss 3.4.19 → 4.3.3 (#214, fechado). Não é bump, é migração de major, e reprovou verify, build-and-size e e2e.

A v4 troca a integração com o PostCSS (@tailwindcss/postcss como pacote próprio, autoprefixer dispensado) e move a configuração para CSS-first (@theme) em vez de tailwind.config.ts.

O tamanho, medido

tailwind.config.ts	198 linhas, ~100 chaves de customização
tokens em app/globals.css	101
arquivos .tsx que consomem utilitárias	451

E a v4 muda semântica de renderização, não só sintaxe: cor de borda default, comportamento de space-*, largura default do ring. Num repo com design system fechado (Sage + Atkinson Hyperlegible + escala própria), isso é diferença visual em telas que ninguém pediu para mudar.

Por que não dá para tratar como bump

O item 12 da Definition of Done exige que mudança de UI seja provada pela tela, em ambiente fresco estilo VPS, com evidência visual. typecheck verde não diz nada sobre um ring que engrossou.

O trabalho

1. postcss.config.mjs → @tailwindcss/postcss, remover autoprefixer.
2. Converter tailwind.config.ts para @theme no CSS.
3. Varredura visual das telas principais nos dois temas, com screenshot antes/depois em evidence/.
4. Conferir os três defaults que mudaram contra o design system.

Sem pressa de segurança: o Tailwind 3.4 segue suportado. É dívida planejada.

[melgarafael]

Concordo com o enquadramento da issue (migração é trabalho próprio, com prova visual — não bump de dependência), e o dimensionamento ficou grande o suficiente para não caber nesta rodada de triagem.

Registro só um achado que economiza um estrago, porque a passada de investigação quase o cometeu: uma varredura de "tokens do tailwind.config sem consumidor" apontou duration-fast/base/slow como mortos, e a conclusão seria deletar o bloco transitionDuration. É falso, medido:

$ grep -rn "duration-fast" app components lib hooks --include="*.tsx" --include="*.ts"
components/ui/button.tsx:23    · components/ui/input.tsx:13
components/ui/badge.tsx:15     · components/ui/textarea.tsx:14

São as quatro primitivas mais reusadas do repo (button importado por 155 arquivos, badge 78, input 68, textarea 28). Compilando o Tailwind com e sem o bloco, com controle positivo:

com o bloco:  .duration-fast { transition-duration: var(--duration-fast) }
sem o bloco:  (nenhuma regra .duration-fast)   — "Done in 133ms", sem erro nem warning

Ou seja: a remoção apagaria a transição de todo botão, input, textarea e badge do produto — em silêncio, com typecheck, lint, test:unit, invariants e build-and-size verdes. Não há rede: grep -rn toHaveScreenshot tests/ devolve 0.

Isso é a própria justificativa da issue medida de perto: numa migração de Tailwind, a classe de regressão que importa é exatamente esta — muda o CSS gerado e nenhum gate atual enxerga. Antes da migração, o item zero é ter prova visual, senão a migração acontece às cegas independentemente de quanto cuidado se tome no resto.