Styleguide para TYPO3

Por que Styleguide é a extensão de QA mais importante para desenvolvedores de templates TYPO3

O desenvolvimento de templates no TYPO3 tem um problema sistemático de qualidade: desenvolvedores testam seus templates Fluid com os dados que existem atualmente no site. Mas elementos de conteúdo têm dezenas de variantes - headlines com e sem subheadline, blocos de texto com 3 palavras ou 3 parágrafos, imagens em formato retrato e paisagem, tabelas com 2 ou 20 colunas. Quem verifica apenas a página atual perde os edge cases que só aparecem após o lançamento.

A extensão Styleguide resolve esse problema criando automaticamente uma árvore de páginas de demo que mostra cada elemento de conteúdo do core em sua própria página. Assim, o desenvolvedor vê imediatamente se seu CSS e seus templates cobrem corretamente todas as variantes.

Cenários típicos de uso

Desenvolvimento de templates em projetos de relançamento. Uma empresa encomenda um relançamento TYPO3 com novo design corporativo. O desenvolvedor frontend cria templates Fluid para todos os elementos de conteúdo. Sem Styleguide, ele precisa criar dados de teste no backend para cada elemento - um processo que com mais de 30 elementos leva horas. Styleguide gera todos os dados de teste automaticamente.

Testes de regressão após atualizações TYPO3. Uma atualização TYPO3 de v11 para v12 altera sutilmente a renderização de elementos de conteúdo individuais. Sem Styleguide, isso só é percebido quando um editor reporta o erro em uma página live. Com Styleguide, o desenvolvedor vê imediatamente após a atualização quais elementos mudaram.

Alinhamento entre equipe de design e desenvolvimento. Designers entregam mockups Figma para 10 elementos de conteúdo. Mas como ficam os 25 elementos padrão restantes no novo design? Styleguide torna essa lacuna visível: cada elemento tem sua própria página de demo, designs ausentes são identificados imediatamente. A Gosign usa Styleguide em cada projeto de relançamento como ferramenta de aprovação para a equipe de design.

Arquitetura técnica

Styleguide é uma extensão oficial do TYPO3 Core System, que desde a v13 está no repositório do Core, mas não faz parte do pacote de código-fonte. É instalada via Composer (typo3/cms-styleguide), até a v12 também pelo TER, e depois ativada.

A extensão trabalha em dois níveis: o TCA Generator cria registros de teste para as próprias tabelas de demo (tx_styleguide_*), que mostram quase todos os tipos de campo TCA do backend. O módulo de backend permite criar e excluir os dados de teste. Uma árvore de páginas própria exibe os elementos gerados no layout frontend, uma página por tipo de conteúdo.

Styleguide não tem dependências externas. Como extensão Core, é atualizada automaticamente com cada atualização TYPO3 e é sempre compatível com a respectiva versão. Importante: Styleguide não gera dados de teste para Custom Content Elements (como Mask ou DCE). Cobre apenas elementos Core.

Problemas frequentes e soluções

Página Styleguide mostra áreas vazias. Os dados de teste foram gerados, mas a página frontend não exibe todos os elementos. Causa: as páginas de demo rodam como site próprio, com template raiz próprio em vez do template do site. Solução: verificar no módulo de backend se a árvore de páginas foi criada corretamente.

Imagens faltam nos dados de teste gerados. Styleguide tenta incluir imagens de teste via FAL. O Styleguide traz imagens de exemplo próprias e as copia para o storage com UID 1; se ele faltar ou estiver mal configurado, campos de imagem ficam vazios. Solução: verificar o storage fileadmin (UID 1) antes de gerar os dados de teste.

Problemas de performance na página Styleguide. Criar as árvores de páginas de demo gera muitos registros de uma vez e, segundo a documentação, leva alguns segundos. Solução: ativar Styleguide apenas no ambiente de desenvolvimento ou staging, nunca no sistema live.

Migração e compatibilidade de versões

Styleguide está no repositório do Core desde o TYPO3 v13 e sai com cada versão do TYPO3. Até a v12 tinha números de versão próprios, o último 12.0.5.

Em um upgrade TYPO3, os dados de teste Styleguide devem ser regenerados após a atualização. O módulo de backend oferece para isso botões separados para excluir e recriar as árvores de páginas de demo. Para TYPO3 v12 e v13, Styleguide está disponível sem restrições.

A Gosign integra Styleguide em cada relançamento TYPO3 como parte fixa do processo de QA. A página Styleguide é criada no ambiente de staging como referência permanente e serve à equipe de design como URL de aprovação.