ryanbbrown/revealjs-skill/revealjs

Reveal.js Presentations

Create HTML presentations using reveal.js. No build step required - just open the HTML in a browser.

What You Create

A reveal.js presentation consists of:

1. HTML file - Contains slides and loads reveal.js from CDN
2. CSS file - Custom styles for layouts, colors, typography, and components

Design Principles

CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:

1. Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
2. Check for branding: If the user mentions a company/organization, consider their brand colors and identity
3. Match palette to content: Select colors that reflect the subject
4. State your approach: Explain your design choices before writing code

Requirements:

• ✅ State your content-informed design approach BEFORE writing code
• ✅ Use web-safe fonts (Arial, Helvetica, Georgia, Verdana, etc.) or Google Fonts via @import in CSS
• ✅ Create clear visual hierarchy through size, weight, and color
• ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
• ✅ Be consistent: repeat patterns, spacing, and visual language across slides
• ✅ Always use `pt` (points) for font sizes - slides are fixed-size, so pt is predictable and familiar (like PowerPoint/Keynote). Never use em, rem, or px for font sizes.

Color Palette Selection

Choosing colors creatively:

• Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
• Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
• Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
• Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
• Ensure contrast: Text must be clearly readable on backgrounds

Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):

1. Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
2. Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
3. Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
4. Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
5. Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
6. Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
7. Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
8. Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
9. Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
10. Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
11. Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
12. Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
13. Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
14. Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
15. Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
16. Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
17. Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
18. Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)

Slide Content Principles

Diverse presentation is key. Even when slides have similar content types, vary the visual presentation:

• Use different layouts across slides: columns on one, stacked containers on another, styled cards on a third
• Mix container styles: plain text, custom styled containers, blockquotes
• Use visual hierarchy: <strong> for key terms, different colors to distinguish categories
• Break up lists with other elements (quotes, styled containers, columns)
• Don't repeat the same layout pattern on consecutive slides

Keep it scannable:

• Short bullet points, not paragraphs
• One main idea per slide when possible
• Use icons (Font Awesome) to add visual interest

When a slide has less content, make it bigger - don't leave empty space with tiny text.

Workflow

Step 1: Plan the Structure

Based on the user's content, determine:

• How many slides are needed
• Which slides should be section dividers (centered, larger text)
• Where to use vertical slide stacks for drill-down content

Step 2: Generate the Scaffold

Use the create-presentation.js script (located in the scripts/ directory next to this SKILL.md file) to generate the HTML scaffold.

node <path-to-skill>/scripts/create-presentation.js --structure 1,1,d,3,1,d,1 --title "My Presentation" --output presentation.html

Finding the script path: The script is at scripts/create-presentation.js relative to where this SKILL.md file is located. Common locations:

• Project skill: .claude/skills/revealjs/scripts/create-presentation.js
• User skill: ~/.claude/skills/revealjs/scripts/create-presentation.js

Options:

• --slides N - Create N horizontal slides (simple mode)
• --structure <list> - Mixed layout with comma-separated values:
• 1 = single horizontal slide
• N (where N > 1) = vertical stack of N slides
• d = section divider slide (centered, no content wrapper)
• --output <file> - Output filename (default: presentation.html)
• --title <text> - Presentation title
• --styles <file> - Custom CSS filename (default: styles.css)

Examples:

# 10 horizontal slides
node <path-to-skill>/scripts/create-presentation.js --slides 10 --output presentation.html
 
# Mixed structure: intro, 2 content slides, divider, 3-slide vertical stack, divider, closing
node <path-to-skill>/scripts/create-presentation.js --structure 1,1,1,d,3,d,1 --title "Q4 Review" --output presentation.html

Step 3: Customize the CSS

The scaffold script automatically copies base-styles.css to your presentation directory as styles.css. Now customize the CSS variables (especially colors) for your presentation theme.

Using Google Fonts: Add an @import at the top of your CSS file:

@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700&family=Lato:wght@300;400;600&display=swap');
 
:root {
  --heading-font: "Playfair Display", Georgia, serif;
  --body-font: "Lato", Helvetica, sans-serif;
  /* ... */
}

The base file includes:

1. CSS Variables for easy customization:

:root {
  /* ===========================================
     BACKGROUND COLOR - Set this first!
     =========================================== */
  --background-color: #ffffff;  /* Change for dark themes (e.g., #1a1a2e) */
 
  /* Typography - ALWAYS use pt for font sizes */
  --heading-font: "Source Sans Pro", Helvetica, sans-serif;
  --body-font: "Source Sans Pro", Helvetica, sans-serif;
  --base-font-size: 32px;  /* Only px value - sets reveal.js base */
  --text-size: 16pt;       /* Base body text - intentionally small */
  --h1-size: 48pt;
  --h2-size: 36pt;
  --h3-size: 24pt;
 
  /* Colors - customize these for each presentation */
  --primary-color: #2196F3;
  --secondary-color: #ff9800;
  --text-color: #222;       /* Use light color (e.g., #FAF7F2) for dark backgrounds */
  --muted-color: #666;      /* Adjust for dark backgrounds too */
}

1. Override reveal.js styles using .reveal prefix:

.reveal {
  font-family: var(--body-font);
}
 
.reveal h1, .reveal h2, .reveal h3 {
  font-family: var(--heading-font);
  text-transform: none;
  color: var(--text-color);
}
 
.reveal p, .reveal li {
  font-size: var(--text-size);
  color: var(--text-color);
}

1. Slide layout styles - control padding and positioning:

.reveal .slides section {
  padding: 40px 60px;
  text-align: left;
}

1. Text size utilities (use these to scale up text when slides have less content):

/* Base text is 16pt - use these classes to increase size when needed */
.text-lg { font-size: 18pt; }    /* Slightly larger */
.text-xl { font-size: 20pt; }    /* Medium emphasis */
.text-2xl { font-size: 24pt; }   /* Strong emphasis */
.text-3xl { font-size: 28pt; }   /* Very large */
.text-4xl { font-size: 32pt; }   /* Maximum body text */
.text-muted { color: var(--muted-color); }
.text-center { text-align: center; }

Typography guidance:

• Base text (--text-size: 16pt) is intentionally small to fit more content
• When a slide has less content, use .text-lg, .text-xl, etc. to fill space appropriately
• This approach prevents overflow on content-heavy slides while allowing flexibility on lighter slides

Custom CSS classes for repeated patterns:

Use inline styles for layout (grids, flex containers) since those vary per slide. But when a visual pattern appears on multiple slides, create a dedicated CSS class in styles.css instead of repeating inline styles. This keeps the HTML clean and ensures consistency. Common examples: stat boxes (number + label), feature cards (icon + title + description), timeline/process steps, profile/bio cards. If an element repeats 3+ times, it should be a class.

Step 4: Fill in the HTML Content

IMPORTANT: Use the Edit tool to fill in slides incrementally — one or a few slides at a time. Do NOT rewrite the entire HTML file with the Write tool. The scaffold generates unique placeholder text per slide (e.g., Slide 2 Title Here), so each section can be targeted with Edit. This is more token-efficient and less error-prone than generating the full file at once.

Follow these patterns:

Standard slide structure:

<section id="unique-slide-id">
  <h2>Slide Title</h2>
  <div class="content">
    <!-- Content here -->
  </div>
</section>

Multi-column layouts - always use inline CSS grid (do NOT create utility classes like .grid-2):

<!-- Equal columns -->
<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 30px;">
  <div>Column 1</div>
  <div>Column 2</div>
</div>
 
<!-- Three columns -->
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 25px;">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>
 
<!-- Unequal columns -->
<div style="display: grid; grid-template-columns: 1fr 2fr; gap: 30px;">
  <div>Narrow sidebar</div>
  <div>Wide main content</div>
</div>

Why inline styles for grids? Each slide's layout needs vary - column ratios, gaps, etc. Inline styles give you full control per-slide without creating dozens of utility classes.

Important HTML patterns:

• Every <section> should have a unique id attribute for stable identification
• Use class="section-divider" for centered section title slides
• Wrap main content in <div class="content"> for consistent spacing. This is a flexbox container that fills the remaining vertical space below the title, ensuring content flows properly.
• Use <div class="footnote"> for attribution or source text at bottom
• All visible text must be inside a text element (<p>, <li>, or <h1>–<h6>). These elements inherit the base font-size, color, and line-height from the CSS. Never put text directly in <span> or <div> — they won't pick up the base styles and will render at the wrong size. Use <div> only as a layout container (for grids, flexbox, etc.), with <p> elements inside it for the actual text.

Step 5: Check for Content Overflow

Run the overflow checker to ensure no slides have content that extends beyond boundaries: