mathews-tom/armory/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):

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.

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/reveal.js@4.5.0/dist/reveal.css
• https://cdn.jsdelivr.net/npm/reveal.js@4.5.0/dist/reveal.js
• https://cdn.jsdelivr.net/npm/reveal.js@4.5.0/plugin/highlight/highlight.js (if code blocks present)
• https://cdn.jsdelivr.net/npm/reveal.js@4.5.0/plugin/highlight/monokai.css (if code blocks present)
• https://unpkg.com/lucide@latest (for icons)

1. Vertical scroll mode — zero CDN dependencies for Reveal.js. Uses custom CSS scroll-snap and vanilla JS for keyboard/scroll navigation.
2. Google Fonts — load fonts matching the theme. Always use <link rel="preconnect"> for performance.
3. Responsive — include media queries for 1400px, 1024px, and 768px breakpoints.
4. Fragment animations — use class="fragment" for progressive reveal in horizontal mode. For vertical mode, use intersection observer fade-in animations.
5. Slide numbers — always show current slide number.
6. Kicker text — each content slide gets a numbered kicker like 01 // Section Name for editorial feel.
7. 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

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