deck-html-primeiro

Deck HTML-Primeiro

Uma abordagem em duas fases para construir um deck personalizado e com ótima aparência que o usuário ainda pode editar no PowerPoint.

Por que este fluxo de trabalho

PowerPoint é o pior lugar para iterar no design visual — lento, complicado, difícil de manter consistência. HTML/CSS é o melhor lugar para iterar: você pode definir um slide, visualizá-lo e refinar espaçamento, cor hierarquia em segundos. Mas o artefato final precisa ser um .pptx real e editável para que o usuário possa ajustar texto e identidade visual em sua própria ferramenta (uma exportação com uma imagem por slide é inútil para eles).

Então: projete em HTML, entregue em PPTX nativo. Você obtém iteração rápida E um resultado editável.

O que está nesta pasta:

Arquivo	O que é
referências/html_prototipo.html	Ponto de partida da Fase 1: três slides, cores da marca como variáveis CSS, navegação por slides
scripts/pptx_helpers.py	Biblioteca auxiliar da Fase 2: geometria, paleta, componentes de cabeçalho / rodapé / cartão / pílula / destaque
scripts/render_diagram.py	Renderiza um SVG desenhado em código para um PNG de alta resolução
scripts/render_pptx.ps1	Exporta cada slide de um .pptx para PNG para verificação (Windows + PowerPoint)
exemplos/exemplo_deck.py	Um deck executável de três slides construído sobre os auxiliares
exemplos/exemplo_diagrama.py	Um gerador de diagrama executável mostrando todas as técnicas da seção de diagrama

Voz — escreva títulos como um consultor, não como um redator publicitário

Leia isto antes de escrever um único título, subtítulo ou linha de corpo. Acertar o layout e errar as palavras produz um deck que o usuário precisa reescrever, o que é pior do que nenhum deck. Isso se aplica a qualquer coisa que vá para a frente de um cliente ou colega — decks, apresentações HTML, dashboards, relatórios de status, one-pagers.

O registro padrão de LLM para slides é um texto chamativo de agência de publicidade. A maioria dos públicos empresariais não o quer. A menos que o usuário peça algo diferente, escreva no registro de um consultor sênior escrevendo para um público executivo: simples, declarativo, específico e finalizado em uma passada.

A regra

Um título afirma o que é o slide. Ele não performa.

Nomeie o conteúdo. Se um leitor que escaneia apenas os títulos não puder reconstruir o argumento, os títulos falharam. Rotulado e numerado vence sempre que engenhoso — Fase 1: Vazamento de Reembolsos diz a um leitor onde eles estão; Aquele com que abrimos não diz nada e os faz ler para descobrir.

Construções a evitar

Não faça	Por que falha	Faça
O dashboard relata. / Não explica.	O ritmo de "preparação e então conclusão". Soa como slogan, não como descoberta.	O dashboard atual relata os números mas não os analisa
Eles abandonaram a última ferramenta por causa de dashboards. / Não venda outro dashboard para eles.	Mesmo ritmo duplo, além de dar uma lição no leitor.	Por que outro dashboard não resolverá isso
Aquele com que abrimos:	Uma isca de dois-pontos que retém a resposta para criar suspense.	Fase 1: Vazamento de Reembolsos
E aqui está como você resolve.	Coloquial, e responde a uma pergunta que ninguém fez.	Correção recomendada e estimativa de construção
Três coisas. Então vamos provar.	Fragmentos staccato usados por ritmo.	O que precisamos desta reunião
O que cai na mesa.	Expressão idiomática no lugar de descrição.	O que entregamos
A cada quinze dias, uma descoberta com um número nela.	Um slogan onde um rótulo pertence.	Cronograma
Só alguém que vê todos os quatro fornecedores vai encontrar isso.	Construção retórica.	Por que nossa equipe está posicionada para fazer este trabalho

Evite também: perguntas retóricas como cabeçalhos; drama de uma palavra (A armadilha, A jogada, O fechamento) como título principal; fragmentos de frase usados para impacto; revelações com travessão; "A questão é"; qualquer coisa que soe como se quisesse ser lida em voz alta.

Concretamente

• Títulos: sintagmas nominais ou afirmações simples. Método de análise. Requisitos de dados e datas de entrega. Perguntas para o cliente. Necessário para executar a Fase 1.
• Numere o trabalho. Fases, níveis, etapas. Fase 1 a Fase 8, Nível 1/2/3. A numeração torna um programa legível e dá às pessoas algo a que se referir em uma reunião.
• Subtítulos carregam o qualificador, não uma piada: Fase 1 · método, Solicitação de dados · Nível 1.
• Texto do corpo: frases completas com sujeito e verbo. Diga a coisa uma vez, corretamente, em vez de três vezes com ênfase crescente.
• Mantenha os específicos. Simples não significa vago. $8,4 milhões no ano até a data com uma taxa de reembolso de 12,5% está exatamente correto. Números, nomes, datas e fontes são o que o tornam crível.
• Negrito com moderação — para a única frase em um parágrafo que carrega o peso, não por ritmo.
• Citações são a exceção. Uma citação literal do cliente pode permanecer literal, e uma única frase genuinamente forte pode ficar em uma citação de destaque — mas apresente-a como uma descoberta, não como um slogan.

Percentuais devem carregar sua base

Percentuais são bons — continue usando-os. Mas um percentual sem base não pode ser julgado. "Os 10% principais dos agentes" significa 2 pessoas se houver 20 agentes e 100 pessoas se houver 1.000; o leitor não pode dizer se é um padrão ou dois indivíduos.

• Coloque a contagem ao lado do percentual, toda vez que for uma parcela de pessoas, coisas ou eventos. Os 6 principais agentes (10% de 60) · 4.100 clientes (0,5% de 820.000) · Fornecedor A recebeu $12,0 milhões, metade de todos os dólares de reembolso ($24,0 milhões).
• Quando o grupo é pequeno, lidere com o número, não com o percentual. Abaixo de ~30 itens, a contagem é a descoberta: 6 agentes emitiram $18.000 vence 10% dos agentes emitiram 20%.
• Dois percentuais lado a lado precisam de ambas as bases. 20% do dinheiro em 12% dos contatos é útil apenas quando o leitor também sabe que são $18.000 de $90.000 e 3.600 de 30.000 contatos.
• Nomeie o denominador. Diga do que é o percentual de: dos dólares de reembolso de agosto, de clientes que reivindicaram pelo menos uma vez, de agentes com 10 ou mais dias trabalhados.
• Diga o que um percentual significa em dinheiro ou pessoas quando puder. "3% foram pagos para uma conta diferente" torna-se 1.500 reembolsos ($150K), 3% do total do ano.
• Descobertas de parcela-do-todo merecem um gráfico de parcela-do-todo, como uma barra empilhada 100%, para que o leitor veja a metade sem fazer aritmética.

Autoverificação: para cada % na página, o leitor pode responder "de quantos?" sem sair da frase? Se não, adicione a contagem.

A autoverificação antes de enviar

Leia os títulos do deck em sequência, por conta própria. Se eles soarem como um sumário, está certo. Se soarem como um pitch, reescreva-os.

Fase 1 — Protótipo em HTML

Construa deck.html com um div .slide por slide em um canvas 16:9 (1280×720). Coloque as cores da marca em variáveis CSS :root (extraia-as do modelo do usuário — veja "Marca" abaixo). Defina cabeçalhos, títulos de seção, cartões, destaques, tabelas. Itere aqui até o design ficar bom — visualize abrindo-o / capturando sua tela, e obtenha a aprovação do usuário sobre estrutura e aparência.

referências/html_prototipo.html é um ponto de partida pronto (capa, um slide com cabeçalho + três cartões + destaque, um slide com imagem, rodapé) com a paleta de variáveis CSS. Leia-o e adapte-o.

Esta fase é o sandbox de design. Não aperfeiçoe cada palavra — acerte o sistema de layout (o cabeçalho, rodapé, estilo de cartão, escala tipográfica, uso de destaque) porque a Fase 2 o espelha.

Torne o protótipo navegável como uma apresentação de slides

Sempre adicione este pequeno script antes de </body> para que a visualização HTML avance como o PowerPoint — clique (ou →/↓/Espaço) vai para o próximo slide, ←/↑ volta. Isso faz a revisão da Fase 1 parecer uma apresentação e é apenas HTML (nada para levar para a Fase 2).

A seleção de texto nunca deve virar a página. As pessoas selecionam texto em slides para copiá-lo. Um arrasto termina em um evento click, então um manipulador de clique simples pula para o próximo slide no meio da cópia. O script abaixo ignora o clique quando o mouse se moveu mais de 5px entre pressionar e soltar, ou quando o texto está selecionado. Um clique real ainda avança.

Um clique deve avançar a partir do slide que foi clicado, nunca de um palpite baseado na posição de rolagem. O palpite escolhe o slide errado em alguns tamanhos de janela, então um clique pula dois slides. As teclas (→/←) ainda podem usar a posição de rolagem, já que não há nada para clicar.

<script>
  /* Visualize como apresentação de slides: clique ou →/↓/Espaço = próximo slide, ←/↑ = anterior. Selecionar texto não avança. */
  (function(){
    var slides=[].slice.call(document.querySelectorAll('.slide'));
    function next(){ var y=scrollY+10; return slides.find(function(s){return s.offsetTop>y;}) || null; }
    function prev(){ var y=scrollY-10, p=null; slides.forEach(function(s){ if(s.offsetTop<y) p=s; }); return p; }
    function to(s){ if(s) s.scrollIntoView({behavior:'smooth',block:'start'}); }
    var downX=0,downY=0;
    addEventListener('mousedown',function(e){ downX=e.clientX; downY=e.clientY; });
    addEventListener('click',function(e){
      if(e.target.closest('a,button,input,textarea,select'))return;
      /* destacar texto, ou arrastar o mouse, não é um clique no slide */
      var sel=window.getSelection&&String(window.getSelection()); if(sel&&sel.trim())return;
      if(Math.abs(e.clientX-downX)>5||Math.abs(e.clientY-downY)>5)return;
      /* avança a partir do slide que foi CLICADO, não de um palpite baseado na posição de rolagem */
      var s=e.target.closest('.slide'); to(s ? slides[slides.indexOf(s)+1] : next());
    });
    addEventListener('keydown',function(e){
      if(['ArrowRight','ArrowDown',' ','PageDown'].indexOf(e.key)>-1){e.preventDefault();to(next());}
      else if(['ArrowLeft','ArrowUp','PageUp'].indexOf(e.key)>-1){e.preventDefault();to(prev());}
    });
  })();
</script>

Se o deck ficar no navegador (uma apresentação de slides em HTML), pare aqui: a Fase 1 é a entrega.

Fase 2 — Gerar o PPTX nativo editável

Recrie o design aprovado com python-pptx para que cada elemento seja editável. Use a biblioteca auxiliar agrupada scripts/pptx_helpers.py — copie-a para a pasta do deck. Ela fornece geometria 16:9, um bloco de paleta de marca e os componentes que você reutilizará em cada slide:

• new_prs(), blank_slide(prs), body_bg(slide)
• add_header(slide, title, meta), add_footer(slide, left, right)
• add_section_title, add_subtitle
• add_text(...) — suporta uma string, uma lista de parágrafos, OU execuções com estilo misto: [[("Parte em negrito ", {"bold": True}), ("parte normal", {"color": MUTED})]]
• add_rect, add_card (faixa de destaque superior/esquerda), add_pill, bulleted, add_takeaway
• add_image(slide, path, x, y, w) — coloca uma imagem em suas próprias proporções
• save_deck(prs, path) — salva, e muda para um novo nome de arquivo se o arquivo estiver bloqueado/aberto

Estrutura (veja exemplos/exemplo_deck.py para um exemplo executável de três slides):

from pptx_helpers import *
def slide_intro(prs): ...      # uma função construtora por slide
def slide_cards(prs): ...
def main():
    prs = new_prs()
    slide_intro(prs); slide_cards(prs)
    print(save_deck(prs, DECK_DIR / "Meu Deck.pptx"))

Regras conquistadas a duras penas (estas previnem as falhas comuns)

• Nunca sobrescreva um arquivo que o usuário tem aberto. O PowerPoint bloqueia o arquivo; um simples prs.save() então lança PermissionError. save_deck() lida com isso incrementando para v2, v3… Mantenha a cópia de trabalho em algum lugar óbvio e informe ao usuário qual arquivo é o mais novo.
• Construa tudo como formas/texto, não como imagem. Esse é o objetivo — eles devem poder editá-lo. Use tabelas reais (slide.shapes.add_table) para comparações densas.
• Defina fontes explicitamente em cada execução (o python-pptx não herdará uma fonte de tema de forma confiável).
• Elimine sombras padrão em autoformas (shape.shadow.inherit = False) e limpe seu texto padrão — os auxiliares já fazem isso.
• Um construtor por slide + um main() que os lista em ordem. Renumere os rodapés lá.

Loop de visualização/verificação (faça isso — não entregue sem ver)

Após cada construção, renderize os slides para PNG e realmente olhe para eles; corrija estouro/espaçamento; reconstrua.

• Windows (PowerPoint instalado):

  powershell -NoProfile -File scripts/render_pptx.ps1 -pptx "Meu Deck.pptx" -outdir preview
  

  Escreve preview/s1.png, s2.png… Ele abre o arquivo como somente leitura, então funciona mesmo enquanto o usuário tem o deck aberto, e deixa o PowerPoint em execução se já estava.
• Sem PowerPoint — libreoffice --headless --convert-to pdf (ou para PNGs) se disponível.

Em seguida, leia os PNGs, ajuste os construtores, execute novamente. Itere até ficar limpo.

Marca (cores + fontes)

Não use uma paleta padrão. Extraia a marca do contexto do usuário: leia o tema de um modelo .pptx (ppt/theme/theme1.xml → <a:clrScheme>), o site/CSS da empresa, ou peça 2–3 cores. Defina-as uma vez nas variáveis :root (HTML) e no bloco BRAND no topo de pptx_helpers.py (PPTX) para que as duas fases coincidam. Defina WORDMARK_PATH como um PNG de logotipo para marcar o cabeçalho, ou deixe None. As cores que acompanham ambos os arquivos são um placeholder neutro; substitua-as.

Diagramas dentro de slides — desenhe-os com código, não os gere

Para o visual principal de um slide (um fluxo, pipeline, funil, arquitetura ou diagrama de processo), não coloque manualmente dúzias de formas do PowerPoint e não use um gerador de imagem com IA. Modelos de imagem são feitos para fotos e arte. Para diagramas eles falham: texto borrado, rótulos com erros ortográficos, formas que não se alinham, cores que fogem da marca, e nada é editável.

Em vez disso, escreva um SVG (um desenho vetorial definido em código: <path>, <circle>, <rect>, <text>, com gradientes e filtros) e renderize-o para um PNG de alta resolução. Um computador desenha cada linha conforme especificação, então é pixel-perfeito, exatamente dentro da marca, repetível e trivialmente editável (altere um código hex ou uma palavra e re-renderize).

Uma analogia para o usuário: pedir a um modelo de imagem um diagrama é como pedir a um artista que desenhe à mão livre uma planta baixa de memória. Escrever código para desenhá-lo é CAD — uma régua e compasso — exato toda vez.

Use para: diagramas de pipeline / fluxo / funil, diagramas de arquitetura, mapas de processo, figuras conceituais,

... [truncado para tradução]