Customização do Tailwind no Hyvä: cores, fontes e safelists

O Tailwind CSS é a parte do Hyvä que mais muda para uma equipe de frontend Magento. No Luma você sobrescreve variáveis e mixins do LESS. No Hyvä você escreve principalmente classes utilitárias nos templates e configura um design system em um só lugar. Bem feito, um tema Hyvä acaba com menos CSS custom do que um tema Luma típico. Mal feito, acaba com o mesmo código hex de cor digitado em duzentos templates. Este artigo é sobre fazer bem: onde a configuração fica, como definir cores e fontes da marca, como escrever estilos de componentes reutilizáveis e como lidar com classes que vêm do banco de dados.

Onde fica o setup do Tailwind

Cada tema Hyvä tem seu próprio build do Tailwind em web/tailwind. Quando você cria um child theme, copia essa pasta do tema pai. O seu tema passa a ser dono do build, da configuração e do web/css/styles.css compilado. Os passos do setup estão no guia de setup do tema Hyvä.

Os arquivos exatos dentro de web/tailwind dependem da versão do Hyvä. As releases do Hyvä baseadas no Tailwind v3 usam um arquivo de config JavaScript, tailwind.config.js, mais um arquivo CSS de origem que importa os estilos dos componentes. As releases recentes do Hyvä migraram para o Tailwind v4, onde a maior parte da configuração do tema é escrita em CSS com a diretiva @theme. As ideias abaixo valem para as duas. Mostro as duas sintaxes onde elas diferem. Confira a versão do Tailwind no seu package.json antes de seguir qualquer exemplo da internet.

Fontes de conteúdo: o que o Tailwind escaneia

O Tailwind só gera CSS para nomes de classe que encontra nos arquivos que escaneia. Em um tema Hyvä esses arquivos são:

• Templates e layout XML do seu próprio tema.
• Templates do tema Hyvä pai, para que as classes usadas ali não se percam.
• Templates de módulos que se registram no build do Hyvä, reunidos em app/etc/hyva-themes.json pelo bin/magento hyva:config:generate.

Se uma classe é usada em um arquivo fora desses paths, ela não estará no CSS compilado. Esse é o problema de Tailwind mais comum em lojas Hyvä, e quase sempre é um content path faltando ou uma classe que só existe no banco de dados.

Um erro clássico é montar nomes de classe dinamicamente em PHP ou JavaScript:

<?php // Tailwind cannot see these classes: ?>
<div class="text-<?= $escaper->escapeHtmlAttr($color) ?>-600"></div>

<?php // Tailwind can see these, because the full class names appear in the file: ?>
<?php $classes = ['red' => 'text-red-600', 'green' => 'text-green-600']; ?>
<div class="<?= $escaper->escapeHtmlAttr($classes[$color] ?? 'text-gray-600') ?>"></div>

O Tailwind escaneia texto, não executa o seu código. Escreva sempre nomes de classe completos em algum lugar onde ele consiga ler.

Cores da marca, fontes e espaçamento

Não espalhe códigos hex pelos templates. Defina a paleta da marca uma vez e use nomes semânticos. O tema padrão do Hyvä já usa cores nomeadas como primary e secondary nos seus templates, então mudar esses valores reestiliza grande parte da loja sem mexer no markup.

Config no estilo Tailwind v3

// web/tailwind/tailwind.config.js (excerpt, Tailwind v3 based Hyvä versions)
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          lighter: '#3b6fd8',
          DEFAULT: '#1d4fb8',
          darker: '#123a8c'
        }
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif']
      }
    }
  }
};

Mantenha o resto da config copiada como está. Ela contém os content paths e o helper do Hyvä que junta a configuração dos módulos. Mude só a seção do tema, a menos que você saiba por que o resto está ali.

Config no estilo Tailwind v4

/* in the theme's source CSS file, Tailwind v4 based Hyvä versions */
@theme {
  --color-primary: #1d4fb8;
  --color-primary-lighter: #3b6fd8;
  --color-primary-darker: #123a8c;
  --font-sans: "Inter", system-ui, sans-serif;
}

Na v4, cada variável CSS em @theme vira um conjunto de utilitários. --color-primary dá bg-primary, text-primary, border-primary e assim por diante. As variáveis também ficam disponíveis como CSS custom properties normais, o que é útil para uma regra ocasional que não dá para expressar com utilitários.

Web fonts

Hospede as fontes você mesmo na pasta web/fonts do tema e declare com @font-face no CSS de origem. Use font-display: swap e faça preload só de um ou dois arquivos usados acima da dobra. Carregar cinco pesos de um serviço externo de fontes desfaz boa parte do que o Hyvä ganha em Core Web Vitals. Veja Core Web Vitals no Magento 2 para saber como as fontes afetam LCP e CLS.

Estilos de componentes reutilizáveis

Classes utilitárias nos templates são o padrão. Mas alguns padrões se repetem em dezenas de templates: botões, inputs de formulário, badges, cards. Para esses, defina uma classe de componente com @apply no CSS do tema, para que o markup fique curto e o estilo mude em um lugar só.

.btn-acme {
  @apply inline-flex items-center px-4 py-2 rounded-md font-semibold;
  @apply bg-primary text-white;
}
.btn-acme:hover {
  @apply bg-primary-darker;
}

O tema padrão do Hyvä já traz estilos de componente para botões, formulários e outros elementos comuns nos seus arquivos CSS de origem. Olhe lá primeiro. Alterar uma classe existente como btn-primary no seu child theme é melhor do que criar uma paralela que metade dos templates usa.

Uma boa regra para saber quando usar @apply: se o mesmo grupo de cinco ou mais utilitários aparece em mais de três templates, é um componente. Se aparece uma vez, deixe os utilitários no template.

Classes vindas do banco de dados

CMS blocks, CMS pages, conteúdo do Page Builder e parâmetros de widgets vivem no banco de dados. O Tailwind nunca os vê. Se um editor digita class="bg-primary text-white p-6" em um CMS block e nenhuma outra coisa no tema usa p-6, o block renderiza sem esse padding.

Há três jeitos de lidar com isso:

1. Faça safelist das classes que os editores podem usar. Na v3 é a chave safelist na config. No Tailwind v4 o equivalente é a diretiva @source inline() no CSS, disponível a partir do Tailwind 4.1.
2. Exporte o conteúdo do CMS para arquivos que o Tailwind escaneia. Algumas equipes mantêm o HTML dos CMS blocks no repositório e fazem o deploy com data patches. Assim os arquivos HTML são só mais um content path. Isso também dá versionamento ao conteúdo, que é um bônus. Data patches estão em declarative schema e data patches.
3. Dê aos editores um conjunto pequeno de classes de componente. Em vez de classes utilitárias livres, documente .cms-banner, .cms-cta e classes parecidas definidas no CSS do tema. Os editores usam essas e o tema controla a aparência.

A opção 3 escala melhor em lojas com muitos editores de conteúdo. Ela também evita que o site vá enchendo aos poucos de estilos avulsos.

// Tailwind v3 safelist example
module.exports = {
  safelist: [
    'bg-primary',
    'text-white',
    { pattern: /^(p|px|py)-(4|6|8)$/ }
  ]
};

Cuidado com safelists por padrão (pattern). Um pattern amplo pode adicionar centenas de kilobytes de CSS que ninguém usa.

Page Builder

A saída do Page Builder em uma loja Hyvä precisa de estilização compatível com o Hyvä para os seus content types. As opções para isso mudaram entre versões do Hyvä, então consulte a documentação atual do Hyvä e decida cedo se a loja vai usar muito o Page Builder. Se o marketing vive no Page Builder, teste os content types mais usados (rows, columns, banners, sliders) no novo tema antes de estimar o resto da migração.

Mantendo o CSS pequeno

• Confira o tamanho do web/css/styles.css depois de cada build. Um salto repentino normalmente significa um novo pattern de safelist ou um content path que agora inclui algo enorme, como uma pasta vendor inteira.
• Não adicione plugins do Tailwind que você não usa.
• Rode o build de produção, não o de desenvolvimento, antes do deploy. O script de produção minifica a saída.
• Evite escrever grandes quantidades de CSS custom nos arquivos de origem. Se você se vir escrevendo muito, veja se um utilitário já faz isso.

Dicas de fluxo de trabalho

Rode o script de watch enquanto trabalha nos templates para que o CSS seja refeito ao salvar. Use as devtools do navegador para confirmar que uma classe está presente no CSS compilado antes de depurar qualquer outra coisa. Ao atualizar o Hyvä, compare a pasta web/tailwind do tema pai com a sua cópia. Versões novas do Hyvä às vezes mudam o setup do build, e o seu child theme não pega essas mudanças automaticamente, porque tem sua própria cópia.

FAQ

Por que uma classe do Tailwind está faltando na minha loja Hyvä?

O Tailwind só gera as classes que encontra nos arquivos escaneados. A classe provavelmente é usada em um CMS block, é montada dinamicamente ou está em um módulo que não consta no app/etc/hyva-themes.json. Faça safelist dela ou adicione o path.

Ainda devo escrever LESS em um tema Hyvä?

Não. O Hyvä não usa o pipeline de LESS do Magento. A estilização é feita com utilitários do Tailwind nos templates, mais um pouco de CSS nos arquivos de origem do Tailwind do tema.

O Hyvä está no Tailwind v3 ou v4?

As releases mais antigas do Hyvä estão no Tailwind v3 e as recentes migraram para a v4. Confira a versão do tailwindcss no web/tailwind/package.json do seu tema antes de seguir exemplos.

Quando devo usar @apply?

Para padrões repetidos em muitos templates, como botões, inputs e badges. Para estilização avulsa, mantenha as classes utilitárias no template.

Atendo como freelancer em Magento e em frontend Hyvä. Se precisar de ajuda com o seu tema, fale comigo.