specsfy-specialist-tailwind-css

Tailwind CSS

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.

1. Traduzir o layout e os estados da interface em constraints responsivas

(breakpoints ou @container) antes de escrever a primeira classe.

1. Reutilizar tokens semânticos já existentes (cor, espaçamento, radius,

tipografia) antes de recorrer a valor arbitrário (w-[137px]).

1. Implementar mobile-first: escrever o estilo base para a tela menor e

sobrepor apenas o que muda nos breakpoints maiores.

1. 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.

1. 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.

1. 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.