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 imageto 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.
- Take topic, audience, and tone.
- Run
slides-grab list-styles, shortlist 2–3 bundled styles, get explicit approval. Optionally offerslides-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 withslides-grab import-templateand recordstyle: template-pack— the template pack supplies design tokens, but slides stay semantic HTML. - Record
mode: htmlinslide-outline.mdmeta. - Present outline, revise until approved.
Stage 2 — Design
Use the installed slides-grab-design skill.
- Read approved
slide-outline.md, load the style spec (src/design-styles-data.jsfor bundled ids,slides-grab show-designforDESIGN.slides.md, or.slides-grab/template-pack.jsonfor imported packs). - Write a visual thesis, content plan, system declaration, and design tokens before generating slides.
- Generate
slide-XX.htmlsemantic HTML files with 2-digit numbering in--slides-dir. - 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— runcodex loginonce; 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 viaOPENAI_API_KEY),--provider nano-banana(Googlegemini-3-pro-image-previewviaGOOGLE_API_KEY/GEMINI_API_KEY, supports--image-size 2K|4K). If credentials are unavailable, fall back to web search + download into<slides-dir>/assets/. - Diagrams: for complex diagrams (architecture, workflows, relationship maps), use
tldrawviaslides-grab tldraw, store under<slides-dir>/assets/. - Charts: default to Chart.js (
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>), start fromtemplates/chart.html, keepanimation: false,responsive: true,maintainAspectRatio: false, wrap<canvas>in a stable container.slides-grab validatereportsempty-canvasfor unpainted canvases. - Video: store under
<slides-dir>/assets/, preferposter="./assets/<file>". Useslides-grab fetch-videooryt-dlpfor web sources. - Icons: prefer Lucide before emoji.
- Run
slides-grab validate --slides-dir <path>. Auto-fix failures until it passes. - 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 untilProceed. Record withslides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <a.md> --pass-b-report <b.md>. - Launch the HTML editor:
slides-grab edit --slides-dir <path>. For chart decks, also runslides-grab build-viewerand confirm charts render inviewer.html.
Stage 3 — Export
Use the installed slides-grab-export skill. Requires a fresh Proceed gate receipt.
- Widescreen →
slides-grab pdf --slides-dir <path> --output <name>.pdf. - Per-slide PNG →
slides-grab png --slides-dir <path> --output-dir <path>/out-png --resolution 2160p. - Card-news →
slides-grab png --slide-mode card-news(see../slides-grab-card-news). - 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 remotehttp(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 validatepasses. - Do not advance to export while any Critical design-gate finding is unresolved.
Reference
../slides-grab-plan/SKILL.mdand../slides-grab-plan/references/../slides-grab-design/SKILL.mdand../slides-grab-design/references/../slides-grab-export/SKILL.mdand../slides-grab-export/references/

