mathews-tom/html-presentation

HTML Presentation Skill

Convert documents, outlines, or freeform content into polished, self-contained HTML slide presentations with keyboard and scroll navigation.

When This Skill Triggers

• User provides a document and asks for a "presentation", "slides", or "deck" as HTML
• User asks to convert notes/outline/content into browser-presentable slides
• User wants a Reveal.js or scroll-based HTML presentation
• User references wanting to present from a browser rather than PowerPoint

Step 0: Gather Requirements

Before generating anything, check whether the user has specified the following. If any are missing, ask for clarification in a single concise message. Do NOT ask more than once — use sensible defaults for anything the user declines to specify.

Required context (ask if missing):

| Parameter | What to ask | Default if not specified | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | Navigation mode | "Should slides go left-to-right (horizontal) or top-to-bottom (vertical scroll)?" | horizontal | | Theme | "Which visual style? Options: dark-editorial (dark bg, serif headlines, editorial feel), light-minimal (clean white, sans-serif), corporate (navy/white, professional), hacker (terminal green-on-black, monospace)" | dark-editorial | | Audience & tone | "Who is this for? (e.g., investors, engineers, conference talk, internal team)" | Infer from content | | Slide count preference | "Roughly how many slides?" | Auto-determine from content density | | Branding | "Any logo text, tagline, or accent color to use in the header?" | None | | CTA / closing | "Any call-to-action, links, or contact info for the final slide?" | None |

If the user provides a document and says something like "make this a presentation", ask all missing parameters in one shot. If they say "just make it look good", use defaults and proceed.

Step 1: Analyze the Source Document

Read the uploaded document or provided content. Identify:

1. Logical sections — these become slides or slide groups
2. Key data points — numbers, metrics, percentages → use metric/stat slide layouts
3. Lists and comparisons — feature lists, pros/cons → use card grids or comparison tables
4. Quotes or testimonials — use quote-block layouts
5. Sequential processes — workflows, timelines → use workflow/timeline slide layouts
6. Title and conclusion — first and last slides get special treatment

Create a mental outline mapping content sections to slide types before writing any HTML.

Step 2: Select Slide Layouts

Each slide should use one of these layout patterns. Mix them for visual variety — never use the same layout for more than 2 consecutive slides.

| Layout | When to Use | CSS Class | | -------------------- | ----------------------------------------------- | ----------------------------------------------- | | Title | Opening slide, section dividers | slide--section slide--center | | Split | Text + supporting content side-by-side | split or split--60-40 | | Grid Cards | 3-6 related items (features, risks, components) | grid-2, grid-3, grid-4 | | Metrics | Key numbers/stats to emphasize | metrics with metric items | | Quote | Expert quotes, testimonials, key statements | quote-block | | Workflow | Sequential process, pipeline, architecture | workflow with arrow connectors | | Comparison Table | Feature comparison, before/after | comparison-table | | Timeline | Chronological events, roadmap phases | timeline | | List | Ordered or unordered key points | list, list--check, list--numbered | | CTA / Closing | Final slide with links and contact | slide--section slide--center + contact-grid |

Step 3: Generate the HTML

Read the appropriate theme and template files from this skill's references directory before writing code:

1. Always read references/THEMES.md to get the CSS variables and styles for the selected theme
2. Always read references/TEMPLATES.md to get the HTML patterns for each slide layout
3. Always read references/NAVIGATION.md to get the correct JS initialization for the selected navigation mode

Then assemble the presentation as a single self-contained HTML file:

File Structure

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Meta, fonts, Reveal.js CDN (horizontal) or custom CSS (vertical) -->
    <!-- All styles inline in <style> block -->
  </head>
  <body>
    <!-- Slides markup -->
    <!-- Scripts: Reveal.js init (horizontal) or custom scroll handler (vertical) -->
  </body>
</html>

Key Rules

1. Single file — everything inline. No external CSS/JS files except CDN resources (Google Fonts, Reveal.js, Lucide icons).
2. CDN dependencies (horizontal mode):
   • https://cdn.jsdelivr.net/npm/[email protected]/dist/reveal.css
   • https://cdn.jsdelivr.net/npm/[email protected]/dist/reveal.js
   • https://cdn.jsdelivr.net/npm/[email protected]/plugin/highlight/highlight.js (if code blocks present)
   • https://cdn.jsdelivr.net/npm/[email protected]/plugin/highlight/monokai.css (if code blocks present)
   • https://unpkg.com/lucide@latest (for icons)
3. Vertical scroll mode — zero CDN dependencies for Reveal.js. Uses custom CSS scroll-snap and vanilla JS for keyboard/scroll navigation.
4. Google Fonts — load fonts matching the theme. Always use <link rel="preconnect"> for performance.
5. Responsive — include media queries for 1400px, 1024px, and 768px breakpoints.
6. Fragment animations — use class="fragment" for progressive reveal in horizontal mode. For vertical mode, use intersection observer fade-in animations.
7. Slide numbers — always show current slide number.
8. Kicker text — each content slide gets a numbered kicker like 01 // Section Name for editorial feel.
9. Header bar — each content slide (not title/section slides) gets a header with an icon and section label.

Horizontal Mode: Reveal.js Config

Reveal.initialize({
  hash: true,
  slideNumber: true,
  controls: true,
  controlsLayout: "bottom-right",
  progress: true,
  center: false,
  transition: "slide",
  width: "100%",
  height: "100%",
  margin: 0.04,
  navigationMode: "linear",
  autoAnimate: true,
  autoAnimateDuration: 0.7,
  plugins: [RevealHighlight], // only if code blocks present
});

Vertical Scroll Mode: Navigation Behavior

• Each slide is a full-viewport section with scroll-snap-align: start
• Arrow keys (Up/Down/Left/Right) all navigate between slides
• Mouse wheel scrolls between slides (debounced)
• Page Up/Down, Home/End supported
• Progress bar at bottom shows position
• Smooth scroll transitions between slides
• Touch swipe support for mobile

Step 4: Write to Output

1. Create the HTML file at an appropriate output path (e.g., ./presentation.html or a user-specified location)
2. Present the file to the user

If the content is large (>15 slides), build iteratively — write the skeleton first, then append slide content in chunks.

Error Handling

| Problem | Cause | Fix | | --------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CDN fails to load (Reveal.js, Lucide, Google Fonts) | Network unavailable or CDN outage | Switch to inline styles/scripts: embed Reveal.js core inline, replace Lucide icons with inline SVG paths, use system font stack (system-ui, -apple-system, sans-serif) | | Content overflows slide viewport | Too much text or too many elements per slide | Split the slide into two: move supporting detail to a follow-up slide or convert prose to a bullet list | | Fonts render incorrectly or fail to load | Google Fonts CDN blocked or slow | Add system font fallback in the font-family stack: 'Font Name', system-ui, Georgia, serif | | Reveal.js fails to initialize | Script load order issue or missing plugin | Verify CDN script tags appear before Reveal.initialize(); check browser console for 404s |

Quality Checklist

Before delivering, verify:

• [ ] All slides render without overflow (content fits viewport)
• [ ] Navigation works with arrow keys AND mouse scroll
• [ ] Slide numbers are visible
• [ ] Fragment animations work (horizontal) or fade-in works (vertical)
• [ ] Links are clickable (pointer-events: auto in Reveal.js)
• [ ] Code blocks have syntax highlighting (if present)
• [ ] Responsive at all three breakpoints
• [ ] No broken icon references (Lucide icons initialized)
• [ ] Consistent kicker numbering across all slides
• [ ] Title slide and closing slide have distinct visual treatment