2026-01-17 — Fix Flux assets/layout (Blade directives + Tailwind v4 dark)
Documentação KOLOS
← Índice docs Início

2026-01-17 — Fix Flux assets/layout (Blade directives + Tailwind v4 dark)

🧭 Contexto

A UI estava com sintomas claros de integração incompleta do Flux:

  • O texto literal @fluxStyles aparecia no topo da página (ou seja: o Blade não estava reconhecendo a diretiva).
  • Componentes com tipografia/spacing estranhos e sobreposição visual.
  • O projeto estava servindo assets buildados (sem public/hot), então ajustes no CSS não refletiam sem rebuild.

✅ Decisão

Baseado no guia oficial embarcado no pacote (vendor/livewire/flux/README.md):

  • Remover a diretiva inexistente @fluxStyles.
  • Manter @fluxScripts (diretiva oficial, injeta JS do Flux e força a injeção de assets do Livewire).
  • Garantir @livewireStyles e @livewireScripts no layout.
  • Alinhar Tailwind v4 com Flux adicionando @custom-variant dark (&:where(.dark, .dark *)); em resources/css/app.css.
  • Remover overrides globais de tipografia (h1/h2/h3) que conflitam com a tipografia dos componentes Flux.
  • Trocar o “canvas” do app (background/text do body) para usar tokens do Flux em CSS (em vez de classes Tailwind no body).
  • Ajustar a estrutura do layout para seguir o CSS do Flux (vendor/livewire/flux/dist/flux.css): sidebar, header e main devem ser irmãos diretos no DOM para o grid layout (*:has(>[data-flux-main]) / *:has(>[data-flux-sidebar]+[data-flux-header])) funcionar corretamente.

Observação: o Flux recomenda @fluxAppearance, porém o KOLOS está em modo dark-only (classe dark fixa no <html>). Manteremos a aparência fixa por enquanto para evitar alternância automática (system/light) que descaracterizaria o tema.

🛠️ Passos

  1. Ajustar o layout base para não emitir diretivas inválidas e incluir Livewire/Flux corretamente.

  2. Ajustar o CSS base conforme o setup recomendado pelo Flux/Tailwind v4.

  3. Rebuild dos assets (já que sem public/hot a aplicação usa public/build).

Comandos:

  • ./vendor/bin/sail npm run build
  • ./vendor/bin/sail artisan test

🧪 Validação

  • Abrir /dashboard e confirmar que não existe @fluxStyles renderizado em HTML.
  • Conferir que a rota retorna 200.
  • Rodar os testes:
    • ./vendor/bin/sail artisan test

📦 Impacto

Arquivos alterados:

  • resources/views/components/layouts/app.blade.php
  • resources/css/app.css

Efeitos colaterais esperados:

  • Sem mais texto cru @fluxStyles no topo.
  • Tipografia global deixa de interferir nos componentes Flux.
  • Dark variant do Tailwind passa a funcionar corretamente com .dark.