req-154: Auditoria, Normalização Visual e Reparo da Compilação de Tailwind CSS nos Templates de Páginas e Componentes

• Status do intake: ready-for-intake

• Data: 2026-09-02

• Origem: relato do operador durante uso da aba "Modelos" e "Visualização" no módulo admin-paginas/adicionar/ ([REDACTED]), onde múltiplos templates de páginas e componentes (ex: "Landing Page de Alta Conversão", "Sessão de Oferta Exclusiva", sessões de 3 colunas, hero banners) apresentaram defeitos visuais graves — perda de margens/paddings internos, perda de cores em botões chamativos, desconstrução do grid/flex em cartões e colapso de espaçamentos

• Classificação: auditoria visual de templates, paridade Tailwind CSS v4, compilador de recursos (c2f resources:sync), isolamento de iframe no editor/preview, integridade de css_precompiled

• Batch candidato: BATCH-156

1. Contexto e Diagnóstico Preliminar de Arquitetura

O Conn2Flow conta com um acervo de 72 templates estáticos (divididos em variantes Tailwind CSS e Fomantic UI) localizados em gestor/resources/pt-br/templates/ e catalogados no manifesto gestor/resources/pt-br/templates.json.

Ao selecionar templates na aba "Modelos" e inspecioná-los na aba "Visualização" (Preview) em admin-paginas/adicionar/, o operador constatou distorções visuais generalizadas:

1. Margens e Espaçamentos Zerados: Blocos de oferta e seções inteiras aparecem colados nas bordas ou centralizados sem padding de contêiner (mx-auto, max-w-*, py-*, px-*);

2. Perda de Cores e Estilos em Botões (CTA): Botões principais (ex: "Quero escalar agora", "Começar Agora") perderam planos de fundo (background-color), estados de hover e sombras, aparecendo transparentes ou desbotados;

3. Cartões e Grades Descontruídos: Seções em grade (ex: 3 colunas, depoimentos, recursos) perderam o padding interno dos cartões e os espaçamentos entre elementos (gap-*, space-y-*), resultando em colapso visual;

4. Divergência contra as Screenshots de Referência: A pasta gestor/assets/templates/images/pt-br/ armazena as capturas visuais oficiais de cada template (referenciadas na chave thumbnail em templates.json), servindo de gabarito visual indiscutível de como os templates devem ser renderizados.

Hipóteses Técnicas para a Investigação

1. Desfasamento ou Incompletude de css_precompiled nos Templates: Os arquivos <id>.precompiled.css dentro de gestor/resources/pt-br/templates/<id>/ foram compilados por versões de pipeline anteriores ou não tiveram suas utility classes atualizadas no build offline (c2f resources:sync).

2. Incompatibilidade ou Classes Não Reconhecidas no Tailwind v4: Classes utilitárias herdadas do Tailwind v3 ou Fomantic UI presentes nos arquivos .html dos templates podem ter sido alteradas ou descontinuadas na versão v4 do motor Tailwind, impedindo que o compilador (@tailwindcss/browser ou CLI) gere as regras correspondentes.

3. Omissão de Preflight / Resets no Preview Iframe: Na aba de visualização do editor em admin-paginas/adicionar/, se o iframe de preview não carrega a folha base/preflight do Tailwind ou sofre interferência de CSS global do painel administrativo, os elementos HTML padrões (botões, seções, parágrafos) regridem para o comportamento nativo do navegador.

4. Filtragem Excessiva no Motor de Baseline / Extraction: As alterações recentes na extração de css_compiled e procedência de CSS podem ter descartado seletores utilitários dos templates por interpretar equivocadamente que já pertenciam ao layout base.

2. Escopo Técnico Requerido

Módulo 1: Auditoria Visual e Sanitização do Acervo de Templates (templates/)

• Localização: gestor/resources/pt-br/templates/ e gestor/resources/en/templates/ (todas as 72 pastas de modelos).

• Ações:

  1. Realizar varredura nos arquivos .html dos templates para identificar e corrigir classes Tailwind obsoletas ou inconsistentes (ex: padding/margin incorretos, sintaxes arbitrárias quebradas, cores descontinuadas);

  2. Comparar a renderização de cada template contra seu respectivo gabarito em gestor/assets/templates/images/pt-br/ (thumbnail), assegurando fidelidade visual completa em contêineres, cartões, botões e tipografia.

Módulo 2: Recompilação e Sincronização dos Arquivos Pré-compilados (.precompiled.css)

• Localização: Compilador de recursos CLI (c2f resources:sync / tailwind-recursos.php).

• Ações:

  1. Garantir que a suíte de compilação varra e processe 100% dos templates em gestor/resources/pt-br/templates/ e gestor/resources/en/templates/;

  2. Gerar e validar os artefatos <id>.precompiled.css com todas as regras utilitárias necessárias (@layer utilities), cores, elevações e layouts responsivos;

  3. Atualizar as versões e checksums correspondentes nos arquivos templates.json.

Módulo 3: Garantia da Injeção de CSS no Iframe de Preview (admin-paginas/adicionar/)

• Localização: gestor/modulos/admin-paginas/ e scripts do editor visual (html-editor-interface.js, html-editor.js).

• Ações:

  1. Verificar se a aba de "Visualização" em admin-paginas/adicionar/ carrega o css_precompiled do template ativo e os resets de layout necessários no iframe de preview;

  2. Garantir que a troca de templates na aba "Modelos" recarregue e aplique dinamicamente o pacote CSS do novo modelo no iframe, sem deixar o preview "pelado" de estilos.

Módulo 4: Suíte Automatizada de Testes de Integridade de Templates

• Localização: tests/Unit/PHP/ e tests/Feature/.

• Cobertura:

  1. Teste automatizado que varre o manifesto templates.json e verifica se 100% dos templates apontam para arquivos .html e .precompiled.css existentes e válidos;

  2. Teste que inspeciona o CSS pré-compilado de cada template e confirma a presença de regras essenciais de contêiner e utilitários (p-, m-, gap-, bg-, rounded-, shadow-).

3. Critérios de Aceite e Validação

1. Paridade Visual com os Thumbnails: Ao adicionar qualquer modelo na aba "Modelos" de [REDACTED] e mudar para "Visualização", a renderização deve corresponder com precisão visual à imagem do thumbnail em gestor/assets/templates/images/pt-br/.

2. Espaçamentos e Cartões Corrigidos: Seções de oferta, cartões em 3 colunas e heros devem apresentar seus paddings internos, margens de contêiner e alinhamentos perfeitamente aplicados.

3. Botões com Cores e Estilos Ativos: Todos os botões de ação (CTA) devem exibir suas cores de fundo, bordas, sombras e efeitos hover originais.

4. Sincronização 100% Limpa: O comando ./c2f resources:sync (ou equivalente) deve executar sem erros e atualizar todos os artefatos pré-compilados dos templates.

5. Suíte Automatizada 100% Verde: Todos os testes PHPUnit e Vitest devem passar com sucesso sem regressões.