nomadamas/slides-grab/slides-grab-html

slides-grab HTML Skill

Build semantic slide-XX.html files where text is real HTML (selectable, editable, accessible) and imagery is generated as supporting accent/hero assets — never as whole-slide rasters. Use this pipeline when the user wants a deck they can edit, when slides contain charts or diagrams, or when no existing template demands pixel-perfect visual matching.

Mode signal

The plan stage records mode: html in slide-outline.md. If no mode is recorded, default to this pipeline.

Bespoke imagery rule

• Use slides-grab image to generate individual hero/accent images that sit beside or behind semantic text inside an HTML slide. The generated image is a supporting visual — text and layout stay in HTML/CSS.
• A bespoke image prompt describes the accent visual only — the atmospheric mood, the hero illustration, the background texture — not the slide's title, body copy, or layout. Let HTML handle text and layout.
• Good prompt: "Atmospheric dawn horizon, cyan and silver tones, dreamy Y2K mood, no text, 16:9" — describes a hero background.
• If you instead need the generated image to BE the whole slide (title, body, layout burned into the raster), use the image-native pipeline (../slides-grab-image/SKILL.md) — semantic HTML is the wrong tool for that.

Workflow

Stage 1 — Plan

Use the installed slides-grab-plan skill.

1. Take topic, audience, and tone.
2. Run slides-grab list-styles, shortlist 2–3 bundled styles, get explicit approval. Optionally offer slides-grab preview-styles. If none fit, propose a custom direction. If the user provides a reference template/PDF/PPTX for color tokens only (not pixel-perfect matching), import it with slides-grab import-template and record style: template-pack — the template pack supplies design tokens, but slides stay semantic HTML.
3. Record mode: html in slide-outline.md meta.
4. Present outline, revise until approved.

Stage 2 — Design

Use the installed slides-grab-design skill.

1. Read approved slide-outline.md, load the style spec (src/design-styles-data.js for bundled ids, slides-grab show-design for DESIGN.slides.md, or .slides-grab/template-pack.json for imported packs).
2. Write a visual thesis, content plan, system declaration, and design tokens before generating slides.
3. Generate slide-XX.html semantic HTML files with 2-digit numbering in --slides-dir.
4. Bespoke imagery: when a slide needs a hero/accent image, run slides-grab image --prompt "<accent-visual prompt>" --slides-dir <path>. The default codex provider reuses the local Codex ChatGPT login (~/.codex/auth.json — run codex login once; no API key required). Save under <slides-dir>/assets/. To guide the style, pass reference images with --reference <path> (repeatable). Optional providers: --provider openai (OpenAI gpt-image-2 via OPENAI_API_KEY), --provider nano-banana (Google gemini-3-pro-image-preview via GOOGLE_API_KEY/GEMINI_API_KEY, supports --image-size 2K|4K). If credentials are unavailable, fall back to web search + download into <slides-dir>/assets/.
5. Diagrams: for complex diagrams (architecture, workflows, relationship maps), use tldraw via slides-grab tldraw, store under <slides-dir>/assets/.
6. Charts: default to Chart.js (<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>), start from templates/chart.html, keep animation: false, responsive: true, maintainAspectRatio: false, wrap <canvas> in a stable container. slides-grab validate reports empty-canvas for unpainted canvases.
7. Video: store under <slides-dir>/assets/, prefer poster="./assets/<file>". Use slides-grab fetch-video or yt-dlp for web sources.
8. Icons: prefer Lucide before emoji.
9. Run slides-grab validate --slides-dir <path>. Auto-fix failures until it passes.
10. Run the design gate (../slides-grab-design/references/design-gate.md): capture PNG evidence, run Pass A (System Contract) + Pass B (Audience Impact), synthesize verdict. Resolve all Critical findings, re-render, re-review until Proceed. Record with slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <a.md> --pass-b-report <b.md>.
11. Launch the HTML editor: slides-grab edit --slides-dir <path>. For chart decks, also run slides-grab build-viewer and confirm charts render in viewer.html.

Stage 3 — Export

Use the installed slides-grab-export skill. Requires a fresh Proceed gate receipt.

1. Widescreen → slides-grab pdf --slides-dir <path> --output <name>.pdf.
2. Per-slide PNG → slides-grab png --slides-dir <path> --output-dir <path>/out-png --resolution 2160p.
3. Card-news → slides-grab png --slide-mode card-news (see ../slides-grab-card-news).
4. PPTX/Figma (experimental / unstable) → slides-grab convert / slides-grab figma.

Rules

• Keep slide size 720pt × 405pt.
• Keep semantic text tags (p, h1-h6, ul, ol, li). Never put text directly in <div>/<span>.
• Backgrounds only on <div>; text only in semantic tags.
• No CSS gradients — use flat fills; rasterize gradients to PNG with Sharp if needed.
• Put local images/videos under <slides-dir>/assets/, reference as ./assets/<file>.
• Allow data: URLs when a slide must be self-contained; never leave remote http(s):// image URLs in saved HTML.
• Prefer Lucide for iconography; avoid emoji unless the brief explicitly asks.
• Keep body copy ≥14pt on a 720pt × 405pt slide; 10pt absolute floor.
• Avoid AI slop tropes (aggressive gradient backgrounds, left-border accent cards, SVG-drawn imagery, generic font stacks, generic 3×2 icon-plus-blurb grids).
• Do not present slides for review until slides-grab validate passes.
• Do not advance to export while any Critical design-gate finding is unresolved.

Reference

• ../slides-grab-plan/SKILL.md and ../slides-grab-plan/references/
• ../slides-grab-design/SKILL.md and ../slides-grab-design/references/
• ../slides-grab-export/SKILL.md and ../slides-grab-export/references/