Governança e Arquitetura do Tailwind CSS v4 no Conn2Flow e Projetos

Diagnóstico de CSS em runtime com Chrome DevTools MCP

Após sincronizar pelo pipeline, siga c2f-agent-visual-inspection: capture screenshot e snapshot em desktop/mobile e após alternar estados dinâmicos. Meça o nó com evaluate_script (getComputedStyle, getBoundingClientRect) e correlacione classes reais, breakpoint, display, posição e overflow com o CSS entregue pelo SQL.

Quando get_css_styles estiver no catálogo da sessão, use-o para examinar regras correspondentes e estilos computados. Compare regras sobrescritas, especificidade, ordem e contexto flex/grid; uma declaração aplicada pode ser inativa por incompatibilidade de contexto. Não trate o indicador visual de estilos inativos do DevTools como uma ferramenta MCP garantida. Sem essa ferramenta, combine medições e inspeção das folhas carregadas, registrando a limitação.

Correlacione com c2f css:audit --url=<rota> e reconstrua derivados pelo c2f css:rebuild autorizado. Não use alterações transitórias no DOM/CSS nem updates diretos em css_compiled como solução final; valide novamente o recurso sincronizado.

⚡ Gatilho Obrigatório

• TRIGGER: Criar, alterar, migrar ou debugar qualquer layout, página, componente ou template com classes do Tailwind CSS v4.
• SKIP APENAS SE: Tarefas puramente de backend em PHP ou APIs sem renderização visual.
• CONSEQUÊNCIA DE IGNORAR: Quebra da cascata CSS (sidebar oculta no desktop), mascaramento de código pelo cache de banco (css_compiled) e descarte de estilos em runtime.

⛔ Regras Invioláveis

1. NUNCA execute comandos manuais via npx (npx tailwindcss, etc.). Use sempre ./c2f resources:sync (ou php atualizacao-dados-recursos.php). Quando a invocação direta for estritamente necessária em depuração local, use exclusivamente os binários locais em node_modules/.bin/tailwindcss.cmd e node_modules/.bin/terser.cmd (Armadilha 17: proibição absoluta de npx).
2. Todo HTML/CSS visual deve residir no Sistema de Recursos: resources/<idioma>/<tipo>/<id>/<id>.html e <id>.json.
3. Metadados JSON: Todo recurso Tailwind DEVE declarar "framework_css": "tailwindcss" em seu arquivo de metadados <id>.json.
4. Templates Dinâmicos em Runtime (Finding F2): Declare dependências de templates dinâmicos no array "tailwind_dependencies": ["id-1", "id-2"] do JSON do recurso pai.
5. Cascata e Media Queries: Nunca use .hidden isolado em páginas filhas que conflitem com lg:flex ou md:block do layout pai; use sempre prefixos explícitos de breakpoint (ex: hidden lg:flex).

🏗️ Autoria vs Derivado (Eliminação do Contorno Manual)

A arquitetura CSS do Conn2Flow separa estritamente os campos de autoria (preservados) dos campos derivados (sempre recalculáveis):

[!CAUTION] Regra de Eliminação do Hack Legacy: A prática antiga de zerar paginas.css_compiled = NULL diretamente no banco era um contorno manual de um problema estrutural. Esta prática é proibida. O procedimento correto é usar c2f css:rebuild para recalcular o CSS derivado a partir da autoria vigente.

🔧 Instrumentos de Medição e Reconstrução de CSS

Em vez de inferir estilização por leitura cega de código, utilize os comandos de auditoria:

c2f css:audit

Audita a procedência (css_source_hash), cobertura de classes e classes Tailwind embutidas em PHP/JS por tabela.

./c2f css:audit

c2f css:audit --url=<rota>

Audita a página composta real (com layout + componentes) e mapeia classes órfãs ao recurso de origem.

./c2f css:audit --url=/transformamp/home

c2f css:rebuild

Reconstrói o CSS derivado (css_precompiled e css_compiled) usando o HTML real do banco como fonte.

./c2f css:rebuild
./c2f css:rebuild --url=/transformamp/home

⚠️ Dívida Técnica: tailwind_sources em PHP/JS

Apontar tailwind_sources para arquivos .php ou .js indica classes utilitárias do Tailwind montadas em tempo de execução via JavaScript ou PHP. Isso viola a arquitetura do Conn2Flow, onde PHP/JS não devem carregar marcação ou estilos.

Classificação: Dívida técnica a eliminar. Ação Corretiva: Mover a geração de classes para componentes/templates dentro do Sistema de Recursos (resources/), onde o compilador Tailwind pode escaneá-las estaticamente.

📋 Registro Obrigatório de tailwind_sources e tailwind_sources_reason

Problema

O compilador prévio de Tailwind analisa unicamente o HTML estático do recurso. Classes utilitárias montadas dinamicamente em PHP (ex: badges de status), manipuladas em JS (classList.toggle('hidden')) ou configuradas em JSON de módulos não entram no bundle gerado, causando falhas visuais silenciosas.

Diretriz Normativa

Para páginas do gestor/site que utilizam classes Tailwind fora do HTML estático, declare os metadados no <id>.json do recurso:

{
  "tailwind_sources": [
    "../../../../modulos/ecommerce/ecommerce-checkout.php"
  ],
  "tailwind_sources_reason": "Classes de badge de status (bg-green-100, text-red-600) são montadas em PHP com base no estado do pedido"
}

Alternativa em Bibliotecas do Core

Para bibliotecas do Core que geram HTML com classes Tailwind, encapsule a paleta dinâmica num elemento <template> inerte no próprio componente HTML do recurso:

<!-- Paleta de classes dinâmicas para o scanner Tailwind -->
<template data-tailwind-palette>
  <span class="bg-green-100 text-green-800 bg-red-100 text-red-800 bg-yellow-100 text-yellow-800"></span>
</template>

[!CAUTION] Sem o registro de tailwind_sources, classes utilitárias usadas exclusivamente em PHP/JS são eliminadas do CSS compilado no build. O erro é silencioso — a página renderiza sem as classes, causando quebra visual sem mensagem de erro.

⚙️ Resolução de Binários Locais e Migração Modular (node_modules/.bin/)

Para garantir imunidade ao cache volátil do NPM e evitar falhas de PATH no Windows (Armadilha 17):

• Todo pipeline ou script que invoca o compilador Tailwind ou minificador Terser deve referenciar diretamente os binários locais em node_modules/.bin/tailwindcss.cmd (Windows) ou node_modules/.bin/tailwindcss (Linux/macOS), sem intermediar chamadas via npx.
• Ao migrar módulos administrativos de Fomantic-UI para Tailwind, consulte e aplique a skill canônica c2f-tailwind-module-migration, respeitando a ordem de bundles ($_GESTOR['tailwind-page-bundle'] = true), as variantes -tailwind em interface_componente_variante() e as classes utilitárias isoladas no HTML de recurso.

Hooks em telas de outros módulos (BL-028)

Marcação injetada por hook em tela alheia usa folha própria e classes específicas do componente. Não injete bundle genérico de utilities depois do pacote da página: isso altera a cascata e pode inverter responsivas da hospedeira. Valide a tela anfitriã em desktop/mobile e a ordem real de folhas. CSS próprio continua sendo autoria em resources/, sincronizado pelo pipeline.

Componente renderizado em contexto alheio pode não resolver @[[var]]@ do seu módulo. Nesse caso use marcador #x# substituído explicitamente no PHP com valor obtido no escopo correto via gestor_variaveis; escape conforme o destino (texto/atributo). Não coloque marcador em comentário: a troca pode consumir a primeira ocorrência. Confira que não sobraram marcadores na resposta e não aplique substituição indiscriminada a componentes cujo contrato já resolve variáveis.