Especialista Tailwind CSS no Specsfy: documentação técnica

Quando usar

• Acionar quando o projeto depende de tailwindcss e a tarefa envolve classe utilitária, tema, variante, responsividade ou dark mode.
• Acionar também para decidir se um padrão visual repetido deve virar token, @apply local ou componente extraído.
• Não acionar para a escolha da biblioteca de componentes em si (Radix, shadcn/ui), usar $specsfy-specialist-shadcn-ui ou $specsfy-specialist-react-ui-components para isso e voltar aqui para o sistema de tokens e classes que os sustenta.
• Combinar com $specsfy-specialist-web-accessibility para contraste, zoom e prefers-reduced-motion.

Fluxo

1. Confirmar a versão do Tailwind, a integração (Vite, PostCSS, framework) e onde os tokens são declarados (tailwind.config.js ou @theme em CSS na v4) — a sintaxe de configuração muda entre gerações.
2. Traduzir o layout e os estados da interface em constraints responsivas (breakpoints ou @container) antes de escrever a primeira classe.
3. Reutilizar tokens semânticos já existentes (cor, espaçamento, radius, tipografia) antes de recorrer a valor arbitrário (w-[137px]).
4. Implementar mobile-first: escrever o estilo base para a tela menor e sobrepor apenas o que muda nos breakpoints maiores.
5. Cobrir estados interativos (hover, focus-visible, disabled, aria-*) e preferências do usuário (dark, motion-reduce, forced-colors) desde a primeira versão do componente, não como retrofit.
6. Extrair um componente (não @apply) quando o padrão repetido representa uma unidade semântica reconhecível (um “Card”, um “Badge”), e não apenas uma coincidência visual entre dois lugares.
7. Validar o CSS gerado no build de produção: nenhuma classe usada dinamicamente deve estar ausente por não ser detectável estaticamente pelo scanner de conteúdo.

Padrões

• Manter cor, espaçamento, radius e tipografia como tokens com nome de intenção (bg-surface, text-muted) sempre que o projeto já tiver um sistema de design — não introduzir valor solto que dribla o token existente.
• Expressar estado (hover, foco, seleção, erro) com variantes do próprio Tailwind (hover:, aria-selected:, data-[state=open]:), nunca escondendo a lógica de estado em concatenação de string opaca fora da vista do build.
• Não usar @apply como substituto geral de componente — ele recria uma folha de estilo tradicional dentro do utility-first e perde a colocação (a classe deixa de estar ao lado do elemento que ela estiliza).
• Garantir que toda classe construída dinamicamente (template string, concatenação condicional) seja detectável estaticamente pelo scanner de conteúdo — usar mapas completos de classes literais em vez de montar a classe por concatenação de partes (text-${color}-500 não funciona: o scanner não executa o template).
• Tratar dark mode, prefers-reduced-motion, prefers-contrast e forced-colors como requisito de design, não como camada opcional adicionada depois.
• Preferir layout fluido (flex, grid, unidades relativas) e @container quando o componente precisa responder ao próprio contêiner (ex.: um card que muda de layout dentro de uma sidebar estreita), não ao viewport inteiro.
• Não multiplicar valores arbitrários (p-[13px], text-[15px]) sem antes perguntar se um novo token de escala deveria existir — um valor arbitrário isolado é aceitável, vários próximos e repetidos indicam token ausente.

Antipadrões

• Classe montada por concatenação de variável (`bg-${color}-500`) — o scanner de conteúdo do Tailwind não executa JS, então essa classe nunca é gerada no CSS final, use um mapa literal de classes completas.
• @apply usado para recriar dezenas de componentes CSS tradicionais — perde a vantagem de colocation do utility-first e cria uma folha de estilo paralela difícil de rastrear.
• Cor, espaçamento ou radius hardcoded (#3b82f6, 17px) ao lado de um sistema de tokens já existente — quebra o tema (claro/escuro, marca) na primeira mudança centralizada.
• Adicionar dark mode, foco visível ou movimento reduzido só depois de uma reclamação de acessibilidade, em vez de tratá-los como parte do componente desde a primeira versão.
• Confundir a responsabilidade desta skill com a escolha de biblioteca de componentes prontos — Tailwind é a camada de utilitários/tema, a escolha de “qual Data Table usar” pertence a $specsfy-specialist-shadcn-ui/$specsfy-specialist-react-ui-components.

Validação

• Rodar o build de produção e inspecionar se alguma classe esperada está ausente do CSS final (sinal de classe não detectável estaticamente).
• Testar em viewports pequenos e grandes, com container real quando o componente usar @container, em zoom 200% e 400% (reflow a 320px de largura equivalente), sem perda de conteúdo ou scroll horizontal indesejado.
• Percorrer hover, focus-visible, disabled, loading, error e selected visualmente e por teclado.
• Checar contraste nos temas claro e escuro, e o comportamento com prefers-reduced-motion/forced-colors ativados no sistema operacional.
• Não declarar um componente “responsivo” ou “acessível” apenas por ter classes sm:/dark: presentes, a evidência acima é obrigatória antes da afirmação.

Skills relacionadas

• $specsfy-specialist-reui para composições React e Tailwind do catálogo gratuito.
• $specsfy-specialist-shadcn-ui para o sistema de componentes construído sobre Tailwind + Radix, este especialista cobre o token/utilitário que o sustenta.
• $specsfy-specialist-react, $specsfy-specialist-nextjs e $specsfy-specialist-astro fornecem o componente/framework onde as classes Tailwind são aplicadas, esta skill não decide estrutura de componente nem fronteira server/client.
• $specsfy-specialist-typescript tipa variantes cva quando o projeto expõe props de estilo fortemente tipadas.
• $specsfy-specialist-react-ui-components e $specsfy-specialist-ui-design para a escolha e composição visual da página.
• $specsfy-specialist-web-accessibility para contraste, zoom, reflow e prefers-reduced-motion em profundidade.

Leia references/standards.md para camadas de tokens, variantes, @container, detecção de classes e migração entre versões, com fontes oficiais.