Estilização de PDF não é tão simples quanto parece
A maior parte das pessoas que chegam até mim perguntando sobre o misterioso caso de styles pdf já tentou de tudo: HTML com CSS normal, depois converteu para PDF e ficou frustrada quando nada ficou parecido. Isso é o ponto de partida mais comum que eu vejo. O problema não é a ferramenta, é a expectativa.
O misterioso caso de styles pdf: por que isso existe
PDF não é um formato web. Ele foi criado para impressão, com posições absolutas, medições em pontos e uma lógica bem diferente da renderização de navegador. Quando você usa bibliotecas como wkhtmltopdf, Puppeteer, ou ferramentas similares, na verdade está traduzindo CSS de tela para CSS de página impressa. E nessa tradução, várias coisas se perdem. Eu já perdi horas debuggando layouts que funcionavam perfeitamente no Chrome e apareciam completamente quebrados no PDF final. Um caso bem específico que eu lembro: eu estava convertendo uma tabela com colunas que tinham larguras definidas em porcentagem e usavam overflow:hidden. No navegador, tudo certo. No PDF, a tabela estourava para fora da página e cortava o conteúdo de forma imprevisível. A solução que funcionou foi trocar as porcentagens por larguras fixas em milímetros e adicionar position:absolute nas células problemáticas. Sim, isso mesmo. Tabelas com posicionamento absoluto dentro de um container relativo só para a conversão. Soa errado? Foi. Funcionou.
O que funciona na prática
Se você quer estilizar PDFs de forma consistente, comece com essa premissa: use layout em bloco simples. Flexbox tem suporte variável dependendo do motor de renderização que você está usando. Grid praticamente não existe na maioria dos conversores. Tabelas, floats e position:absolute funcionam de forma mais previsível. O tamanho da página também importa muito. A4 é padrão, mas margens mínimas de 10mm em todos os lados são necessárias na prática, senão o conversor corta conteúdo nas bordas. Eu costumo definir margens de 15mm só para ter margem de segurança.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Fontes são outro ponto onde as pessoas tropeçam. Web fonts raramente funcionam porque o arquivo CSS que carrega a fonte pode não ser resolvido durante a conversão. A solução mais segura é embutir a fonte diretamente ou usar fontes do sistema. Helvetica, Arial, Times New Roman são sempre uma aposta certa se você não pode controlar o ambiente de renderização. Imagens também merecem atenção. SVG funciona bem na maioria dos casos. JPEG compactado demais fica terrível em PDFs de alta resolução. PNG com transparência às vezes gera artefatos. Eu recomendo usar imagens em 300dpi no mínimo para impressão e evitar transparência quando possível.
Limitações que ninguém menciona
Vou ser direto aqui porque isso é importante: nenhum conversor HTML-para-PDF é perfeito. O melhor cenário que eu vi pessoalmente foi usando o PrinceXML para documentos corporativos com layout complexo. Ele suporta quase tudo que CSS oferece, mas custa caro e exige configuração manual. Alternativas gratuitas como WeasyPrint ou Puppeteer funcionam bem para relatórios simples, mas vão falhar em documentos com design system complexo, animações CSS ou JavaScript dinâmico que depende de tempo de execução. Se o seu documento precisa de interatividade, formulários preenchíveis ou geração dinâmica de conteúdo baseada em dados do usuário, considere gerar o PDF de outra forma. Templates com substituição de variáveis em ferramentas como ReportLab (Python) ou libraries semelhantes dão controle total sobre cada elemento na página, mas exigem escrever código procedural em vez de apenas estilizar HTML.
Para quem quer começar, o caminho mais acessível hoje é Puppeteer com o chrome-pdf. Você define o HTML, aplica o CSS que conseguir, e controla o output via código Node.js. Dessa forma consegue injetar dados dinamicamente e fazer screenshot antes de converter. Isso resolveu meu problema com aquela tabela quebrada que citei acima, porque eu finalmente consegui inspecionar o PDF frame a frame e ver exatamente onde o layout estava falhando. Não existe solução mágica. Existe escolha consciente do tooling certo para o tipo de documento que você precisa gerar.
