Deck HTML primero

¿Qué hace Deck HTML primero?

Un flujo de trabajo en dos fases para construir un deck personalizado y de gran aspecto que el usuario aún pueda editar en PowerPoint.

Por qué este flujo de trabajo

PowerPoint es el peor lugar para iterar sobre el diseño visual: lento, complicado, difícil de mantener consistente. HTML/CSS es el mejor lugar para iterar: puedes maquetar una diapositiva, previsualizarla y refinar el espaciado, el color y la jerarquía en segundos. Pero el artefacto final debe ser un .pptx real y editable para que el usuario pueda ajustar el texto y la marca en su propia herramienta (una exportación de imágenes por diapositiva les es inútil).

Por lo tanto: diseña en HTML, entrega en PPTX nativo. Obtienes iteración rápida Y un resultado editable.

Qué hay en esta carpeta:

Archivo	Qué es
references/html_prototype.html	Punto de partida de la Fase 1: tres diapositivas, colores de marca como variables CSS, navegación tipo slideshow
scripts/pptx_helpers.py	Biblioteca auxiliar de la Fase 2: geometría, paleta, componentes de encabezado/pie/página/tarjeta/píldora/conclusión
scripts/render_diagram.py	Renderiza un SVG dibujado con código a un PNG de alta resolución
scripts/render_pptx.ps1	Exporta cada diapositiva de un .pptx a PNG para verificación (Windows + PowerPoint)
examples/example_deck.py	Un deck de tres diapositivas ejecutable construido sobre los helpers
examples/example_diagram.py	Un generador de diagramas ejecutable que muestra cada técnica de la sección de diagramas

Voz: escribe títulos como un consultor, no como un redactor publicitario

Lee esto antes de escribir un solo título, subtítulo o línea de cuerpo. Conseguir el diseño correcto y las palabras incorrectas produce un deck que el usuario tiene que reescribir, lo que es peor que ningún deck. Esto aplica a todo lo que va delante de un cliente o colega: decks, presentaciones HTML, paneles, informes de estado, one-pagers.

El registro predeterminado de los LLM para diapositivas es copia publicitaria impactante. La mayoría de las audiencias empresariales no lo quieren. A menos que el usuario pida otra cosa, escribe en el registro de un consultor senior escribiendo para una audiencia ejecutiva: simple, declarativo, específico y terminado de una sola vez.

La regla

Un título declara de qué trata la diapositiva. No actúa.

Nombra el contenido. Si un lector que escanea solo los títulos no puede reconstruir el argumento, los títulos han fallado. Etiquetado y numerado gana a ingenioso siempre: Fase 1: Fuga de Reembolsos le dice al lector dónde está; La que abrimos no les dice nada y les obliga a leer para descubrirlo.

Construcciones a evitar

No hagas	Por qué falla	Haz
El panel informa. / No explica.	El doble compás "configuración luego remate”. Se lee como un eslogan, no como un hallazgo.	El panel actual informa los números pero no los analiza
Dejaron caer la última herramienta por los paneles. / No les vendas otro panel.	Mismo doble compás, además sermonea al lector.	Por qué otro panel no resolverá esto
La que abrimos:	Una provocación de dos puntos que retiene la respuesta para crear suspense.	Fase 1: Fuga de Reembolsos
Y así es como lo arreglas.	Coloquial, y responde a una pregunta que nadie hizo.	Arreglo recomendado y estimación de construcción
Tres cosas. Luego vamos y lo probamos.	Fragmentos entrecortados usados para ritmo.	Qué necesitamos de esta reunión
Lo que cae sobre la mesa.	Modismo en lugar de una descripción.	Qué entregamos
Cada quince días, un hallazgo con un número.	Un eslogan donde pertenece una etiqueta.	Cronograma
Solo alguien que vea a los cuatro proveedores encontrará esto.	Acumulación retórica.	Por qué nuestro equipo está posicionado para hacer este trabajo

También evita: preguntas retóricas como encabezados; drama de una palabra (La trampa, La jugada, El cierre) como el título principal; fragmentos de oraciones usados para impacto; revelaciones con raya; "Aquí está la cuestión"; cualquier cosa que suene como si quisiera ser leída en voz alta.

Concretamente

• Títulos: frases nominales o declaraciones simples. Método de análisis. Requisitos de datos y fechas de entrega. Preguntas para el cliente. Necesario para ejecutar la Fase 1.
• Numera el trabajo. Fases, niveles, pasos. Fase 1 a Fase 8, Nivel 1/2/3. La numeración hace legible un programa y da a la gente algo a lo que referirse en una reunión.
• Los subtítulos llevan el calificador, no una broma: Fase 1 · método, Solicitud de datos · Nivel 1.
• Cuerpo del texto: oraciones completas con sujeto y verbo. Di la cosa una vez, correctamente, en lugar de tres veces con énfasis creciente.
• Mantén los detalles. Simple no significa vago. $8.4M hasta la fecha a una tasa de reembolso del 12.5% es exactamente correcto. Números, nombres, fechas y fuentes son lo que lo hace creíble.
• Negrita con moderación — para la única frase de un párrafo que lleva el peso, no para el ritmo.
• Las citas son la excepción. Una cita textual de un cliente puede permanecer textual, y una oración única realmente sólida puede colocarse en una cita destacada — pero exprésala como un hallazgo, no como un eslogan.

Los porcentajes deben llevar su base

Los porcentajes son buenos — sigue usándolos. Pero un porcentaje sin base no se puede juzgar. "El 10% superior de los agentes" significa 2 personas si hay 20 agentes y 100 personas si hay 1,000; el lector no puede saber si es un patrón o dos individuos.

• Pon el recuento junto al porcentaje, cada vez que sea una parte de personas, cosas o eventos. Los 6 agentes principales (10% de 60) · 4,100 clientes (0.5% de 820,000) · El Proveedor A recibió $12.0M, la mitad de todos los dólares de reembolso ($24.0M).
• Cuando el grupo es pequeño, lidera con el número, no con el porcentaje. Con menos de ~30 ítems, el recuento es el hallazgo: 6 agentes emitieron $18,000 supera a 10% de los agentes emitieron el 20%.
• Dos porcentajes uno al lado del otro necesitan ambas bases. 20% del dinero en el 12% de los contactos solo es útil una vez que el lector también sabe que son $18,000 de $90,000 y 3,600 de 30,000 contactos.
• Nombra el denominador. Di de qué es el porcentaje de: de los dólares de reembolso de agosto, de los clientes que reclamaron al menos una vez, de los agentes con 10 o más días trabajados.
• Di qué significa un porcentaje en dinero o personas cuando puedas. "El 3% se pagó a una cuenta diferente" se convierte en 1,500 reembolsos ($150K), el 3% del total del año.
• Los hallazgos de parte-del-todo merecen un gráfico de parte-del-todo, como una barra apilada al 100%, para que el lector vea la mitad sin hacer aritmética.

Autoverificación: por cada % en la página, ¿puede el lector responder "¿de cuántos?" sin salir de la oración? Si no, añade el recuento.

La autoverificación antes de enviar

Lee los títulos del deck en secuencia, por sí solos. Si se leen como una tabla de contenidos, está bien. Si se leen como un discurso de ventas, reescríbelos.

Fase 1 — Prototipo en HTML

Construye deck.html con un div .slide por diapositiva en un lienzo 16:9 (1280×720). Pon los colores de la marca en variables CSS :root (extráelos de la plantilla del usuario — ver "Marca" abajo). Diseña encabezados, títulos de sección, tarjetas, llamadas, tablas. Itera aquí hasta que el diseño esté bien — previsualiza abriéndolo / capturándolo, y obtén la aprobación del usuario sobre la estructura y el aspecto.

references/html_prototype.html es un punto de partida listo (portada, una diapositiva de encabezado + tres tarjetas + conclusión, una diapositiva de imagen, pie de página) con la paleta de variables CSS. Léelo y adáptalo.

Esta fase es el arenero de diseño. No perfecciones cada palabra — clava el sistema de diseño (el marco de encabezado/pie, el estilo de tarjeta, la escala tipográfica, el uso de acentos) porque la Fase 2 lo refleja.

Haz que el prototipo sea navegable como un slideshow

Siempre añade este pequeño script antes de </body> para que la vista previa HTML avance como PowerPoint — haz clic (o →/↓/Espacio) va a la siguiente diapositiva, ←/↑ vuelve. Hace que la revisión de la Fase 1 se sienta como presentar y es solo HTML (nada que llevar a la Fase 2).

Resaltar texto nunca debe pasar la página. La gente selecciona texto en las diapositivas para copiarlo. Un arrastre termina en un evento click, por lo que un manejador de clic simple salta a la siguiente diapositiva a mitad de copia. El script a continuación ignora el clic cuando el ratón se movió más de 5px entre pulsación y liberación, o cuando hay texto seleccionado. Un clic real aún avanza.

Un clic debe avanzar desde la diapositiva que se hizo clic, nunca desde una suposición basada en la posición de desplazamiento. La suposición elige la diapositiva equivocada en algunos tamaños de ventana, por lo que un clic salta dos diapositivas. Las teclas (→/←) aún pueden usar la posición de desplazamiento, ya que no hay nada que hacer clic.

<script>
  /* Previsualiza como un slideshow: clic o →/↓/Espacio = siguiente diapositiva, ←/↑ = anterior. Seleccionar texto no avanza. */
  (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;
      /* resaltar texto, o arrastrar el ratón, no es un clic en la diapositiva */
      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;
      /* avanza desde la diapositiva en la que se HIZO CLIC, no desde una suposición basada en la posición de desplazamiento */
      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>

Si el deck se queda en el navegador (un slideshow HTML), detente aquí: la Fase 1 es el entregable.

Fase 2 — Genera el PPTX nativo editable

Recrea el diseño aprobado con python-pptx para que cada elemento sea editable. Usa la librería auxiliar incluida scripts/pptx_helpers.py — cópiala en la carpeta del deck. Proporciona geometría 16:9, un bloque de paleta de marca y los componentes que reutilizarás en cada diapositiva:

• 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(...) — soporta un string, una lista de párrafos, O ejecuciones de estilo mixto: [[("Parte en negrita ", {"bold": True}), ("parte normal", {"color": MUTED})]]
• add_rect, add_card (franja de acento superior/izquierda), add_pill, bulleted, add_takeaway
• add_image(slide, path, x, y, w) — coloca una imagen en sus propias proporciones
• save_deck(prs, path) — guarda, y cambia a un nuevo nombre de archivo si el archivo está bloqueado/abierto

Estructura (ver examples/example_deck.py para un ejemplo ejecutable de tres diapositivas):

from pptx_helpers import *
def slide_intro(prs): ...      # una función constructora por diapositiva
def slide_cards(prs): ...
def main():
    prs = new_prs()
    slide_intro(prs); slide_cards(prs)
    print(save_deck(prs, DECK_DIR / "Mi Deck.pptx"))

Reglas ganadas con esfuerzo (evitan los fallos comunes)

• Nunca sobrescribas un archivo que el usuario tiene abierto. PowerPoint bloquea el archivo; un simple prs.save() luego lanza PermissionError. save_deck() maneja esto incrementando a v2, v3… Mantén la copia de trabajo en algún lugar obvio y dile al usuario cuál es el archivo más nuevo.
• Construye todo como formas/texto, no como una imagen. Ese es el punto — deben poder editarlo. Usa tablas reales (slide.shapes.add_table) para comparaciones densas.
• Establece fuentes explícitamente en cada ejecución (python-pptx no heredará una fuente de tema de manera confiable).
• Elimina sombras predeterminadas en autoformas (shape.shadow.inherit = False) y limpia su texto predeterminado — los helpers ya hacen esto.
• Un constructor por diapositiva + un main() que los enumera en orden. Renumera los pies de página allí.

Bucle de previsualización/verificación (haz esto — no envíes sin ver)

Después de cada construcción, renderiza las diapositivas a PNG y míralas realmente; corrige desbordamientos/espaciados; reconstruye.

• Windows (PowerPoint instalado):

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

  Escribe preview/s1.png, s2.png… Abre el archivo como solo lectura, por lo que funciona incluso mientras el usuario tiene el deck abierto, y deja PowerPoint ejecutándose si ya lo estaba.
• Sin PowerPoint — libreoffice --headless --convert-to pdf (o a PNG) si está disponible.

Luego lee los PNG, ajusta los constructores, vuelve a ejecutar. Itera hasta que esté limpio.

Marca (colores + fuentes)

No uses una paleta predeterminada. Extrae la marca del contexto del usuario: lee el tema de una plantilla .pptx (ppt/theme/theme1.xml → <a:clrScheme>), el sitio/CSS de la empresa, o pide 2–3 colores. Establécelos una vez en las variables :root (HTML) y el bloque BRAND en la parte superior de pptx_helpers.py (PPTX) para que las dos fases coincidan. Establece WORDMARK_PATH en un PNG de logotipo para marcar el encabezado, o déjalo en None. Los colores que vienen en ambos archivos son un marcador de posición neutro; reemplázalos.

Diagramas dentro de diapositivas — dibújalos con código, no los generes

Para el visual principal de una diapositiva (un diagrama de flujo, pipeline, embudo, arquitectura o proceso), no coloques a mano docenas de formas de PowerPoint y no uses un generador de imágenes de IA. Los modelos de imagen están diseñados para fotos y arte. Para diagramas fallan: texto borroso, etiquetas mal escritas, formas que no se alinean, colores que se desvían de la marca, y nada es editable.

En su lugar, escribe un SVG (un dibujo vectorial definido en código: <path>, <circle>, <rect>, <text>, con degradados y filtros) y renderízalo a un PNG de alta resolución. Un ordenador dibuja cada línea según las especificaciones, por lo que es nítido a nivel de píxel, exactamente en línea con la marca, repetible y trivialmente editable (cambia un código hexadecimal o una palabra y vuelve a renderizar).

Una analogía para el usuario: pedirle a un modelo de imagen un diagrama es como pedirle a un artista que dibuje a mano alzada un plano de memoria. Escribir código para dibujarlo es CAD — una regla y un compás — exacto cada vez.

Úsalo para: diagramas de pipeline/flujo/embudo, diagramas de arquitectura, mapas de proceso, figuras conceptuales...