majiayu000 Writing reveal.js Presentations
Core principle: Every reveal.js feature must serve a communication purpose.
Pre-Flight Check (MANDATORY)
Before ANY work, scan existing presentation:
□ Inline style= attributes found?
□ .slide1, .slide2 CSS classes found?
If YES to either → Refactor ENTIRE presentation first
Also check for:
□ Code examples present? Plan for proper sizing (text-base minimum, never smaller than body text)
□ Technical content? Add detailed speaker notes with timing markers (3-5x slide content)
□ Complex concepts? Plan progressive reveal with fragments
□ Creating new presentation? Use typography scale and semantic colors from start
Refactoring workflow when anti-patterns detected:
- Say to user: "I'll refactor to Tailwind CSS while maintaining your colors/aesthetic, then add new slides."
- Add Tailwind CDN:
<script src="https://cdn.tailwindcss.com"></script> - Refactor ALL slides: Remove
style=and.slideNclasses, replace with Tailwind +data-background-* - Then proceed with user's request
"Same style" = same colors/visual design, NOT same implementation.
If you extend bad patterns instead of refactoring, you have violated this skill.
Core Patterns
Tailwind CSS for All Styling
Setup:
<head>
<script src="https://cdn.tailwindcss.com"></script>
</head>
Usage:
<!-- ✅ GOOD -->
<section data-background-color="#1e293b">
<h1 class="text-6xl font-bold text-slate-100 mb-8">Title</h1>
</section>
<!-- ❌ BAD -->
<section class="slide1" style="background: red;">
<h1 style="font-size: 48px;">Title</h1>
</section>
Purpose-Driven Effects
NOT valid purposes: "Draws attention", "looks cool", "makes it engaging", "user asked for flashy"
ACTUAL purposes: Shows transformation, implies progression, emphasizes relationship, indicates topic change
<!-- ✅ Shows transformation -->
<section data-auto-animate>
<div data-id="box" class="h-12 w-12 bg-blue-500"></div>
</section>
<section data-auto-animate>
<div data-id="box" class="h-48 w-48 bg-blue-500"></div>
</section>
<!-- ❌ Effect without purpose -->
<section data-transition="zoom">
<h1>Features</h1>
</section>
Default: data-transition="slide" or none unless you have specific reason.
Content Structure
| Pattern | Use For | Code |
|---|---|---|
| Horizontal slides | Main narrative flow | <section>Topic</section> |
| Vertical slides | Optional detail on topic | Nested <section> |
| Fragments | Progressive reveal | class="fragment" |
<section><!-- Main point -->
<section><h2>Overview</h2></section>
<section><!-- Vertical: detail --><h3>Details</h3></section>
</section>
Speaker Notes (MANDATORY)
Every slide must have properly formatted speaker notes.
<aside class="notes">
<p><strong>Key Points:</strong></p>
<ul>
<li>Point 1 with context</li>
<li>Point 2 with timing</li>
</ul>
<p>Additional detail for presenter.</p>
</aside>
Format requirements:
- Use
<p>,<ul>/<ol>,<strong>/<em> - Break up long text for legibility
Code Examples in Slides
CRITICAL RULE: Code font size must be >= body text font size. Check body text size FIRST, then match or exceed it for code.
<!-- ✅ GOOD: Code matches body text size -->
<p class="text-xl">Explanation text</p>
<pre><code class="language-javascript text-xl" data-trim>
function example() {
return "Same size as body text";
}
</code></pre>
<!-- ❌ BAD: Code smaller than body text -->
<p class="text-xl">Explanation text</p>
<pre><code class="language-javascript text-base" data-trim>
// WRONG: text-base (16px) < text-xl (20px)
</code></pre>
Formatting rules:
- STEP 1: Identify body text size on your slide (
text-xl,text-lg,text-base, etc.) - STEP 2: Set code size to match or exceed: If body is
text-xl, code must betext-xlor larger - Always use
data-trimto remove indentation - Use specific language classes:
language-yaml,language-bash,language-javascript, etc. - Limit to 3-8 lines per block - split longer examples across slides
- Use
data-line-numbersto highlight specific lines when needed
If code doesn't fit: Reduce code lines (3-8 max), split across slides, or reduce BOTH body and code text sizes together.
Progressive reveal with fragments:
<div>
<p>First explain the concept</p>
<pre class="fragment"><code class="language-python text-base" data-trim>
# Code appears after explanation
def example():
return "builds understanding"
</code></pre>
</div>
Typography Scale Reference
Hierarchy for presentations (optimized for projectors):
| Element | Classes | Use For |
|---|---|---|
| Main title | text-6xl font-bold |
Opening slide title |
| Section header | text-4xl or text-5xl font-bold |
Slide titles |
| Subsection | text-2xl or text-3xl font-semibold |
Sub-headings |
| Body text | text-xl |
Main content |
| Supporting text | text-base or text-lg |
Details |
| Code blocks | text-base or text-lg |
Never smaller than body text |
| Footnotes | text-sm |
Minor details only |
CRITICAL RULE: Code font size must be >= body text font size. NO EXCEPTIONS.
Examples - Body text at different sizes:
- Body text
text-2xl→ Code must betext-2xlor larger - Body text
text-xl→ Code must betext-xlor larger - Body text
text-lg→ Code must betext-lgor larger - Body text
text-base→ Code must betext-baseor larger
If code doesn't fit at required size:
- Reduce lines of code (3-8 lines max per block)
- Split across multiple slides with fragments
- Use smaller body text size (and match code size down)
- NEVER reduce code size below body text
Why this matters: Projectors and distance viewing make code the hardest content to read. It must never be smaller than body text.
Semantic Color Patterns
Use Tailwind color utilities to reinforce meaning:
| Purpose | Color | Example Classes |
|---|---|---|
| Positive/Good/Success | Green | text-green-300, text-green-400, bg-green-900 |
| Negative/Bad/Error | Red | text-red-300, text-red-400, bg-red-900 |
| Warning/Caution | Yellow | text-yellow-300, text-yellow-400, bg-yellow-900 |
| Neutral/Info/Refactor | Blue | text-blue-300, text-blue-400, bg-blue-900 |
| Subdued/Meta | Slate | text-slate-400, text-slate-500 |
Slide backgrounds: Alternate #1e293b (slate-800) and #0f172a (slate-900) for visual rhythm.
Accessibility: Don't rely on color alone - use symbols (✅/❌) or text labels too.
Speaker Notes with Timing Markers
MANDATORY: Every slide must have detailed speaker notes with timing estimates.
<aside class="notes">
<p><strong>Introduction (30 seconds):</strong></p>
<ul>
<li>Open with relatable scenario</li>
<li>Pause for audience reaction</li>
<li>Transition to solution</li>
</ul>
<p><strong>Delivery tip:</strong> Make eye contact before revealing next fragment.</p>
</aside>
Requirements:
- Include timing estimate for each section: "(30 seconds)", "(60 seconds)", etc.
- Detail ratio: Notes should contain 3-5x more context than visible on slides
- Structure: Bold headings, bulleted points, delivery tips
- Content: Not just slide recap - include transitions, audience engagement, what to emphasize
Multi-Column Layouts
Use Tailwind grid for side-by-side comparisons:
<!-- Two-column comparison (good vs bad, before vs after) -->
<div class="grid grid-cols-2 gap-8">
<div>
<h3 class="text-3xl text-red-400 mb-4">❌ Before</h3>
<pre><code class="language-python text-base" data-trim>
# Old approach
</code></pre>
</div>
<div>
<h3 class="text-3xl text-green-400 mb-4">✅ After</h3>
<pre><code class="language-python text-base" data-trim>
# New approach
</code></pre>
</div>
</div>
Use gap-4, gap-6, or gap-8 for spacing. Larger gap for dense content.
Progressive Reveal Patterns
When to use fragments:
- Building up complex concepts step-by-step
- Revealing answers after questions
- Showing multiple examples sequentially
- Pacing discussion points
When NOT to use fragments:
- Simple lists where order doesn't matter
- Content that makes sense as a whole
- Every single line (causes "click fatigue")
<!-- ✅ GOOD: Build up complexity -->
<div>
<p class="text-2xl mb-4">First introduce the concept</p>
<ul class="text-xl space-y-2">
<li class="fragment">Then first detail</li>
<li class="fragment">Then second detail</li>
</ul>
<pre class="fragment"><code>...example code appears last</code></pre>
</div>
<!-- ❌ BAD: Every line fragmented -->
<p class="fragment">This</p>
<p class="fragment">causes</p>
<p class="fragment">click</p>
<p class="fragment">fatigue</p>
Fragment modifiers:
fragment fade-in- Defaultfragment fade-in-then-semi-out- Highlight then dimfragment highlight-current-blue- Highlight temporarily
Editing Existing Presentations
When adding to or modifying existing presentations:
- Read entire file first - Understand full structure and patterns
- Identify and match patterns:
- Background colors: Note alternating pattern (e.g., #1e293b, #0f172a)
- Typography: Check existing heading sizes, body text sizes
- Code blocks: Match existing code font size (
text-baseortext-lg) - Speaker notes: Match existing format (timing markers, detail level)
- Fragment usage: Follow existing progressive reveal patterns
- Update related content:
- If changing slide content, update speaker notes to match
- Maintain semantic color usage (green=good, red=bad, etc.)
- Keep same transition style throughout
- Verify rendering:
- All changes display correctly
- No overflow or layout breaks
- Consistent with surrounding slides
What to preserve:
- Color palette and background patterns
- Typography scale hierarchy
- Code sizing conventions
- Speaker note format and detail level
- Fragment usage patterns
What to refactor anyway:
- Inline styles → Tailwind CSS (always)
- Class-based slides → data-background-* attributes (always)
- Missing speaker notes → Add with timing markers (always)
- Code smaller than body text → Fix to text-base minimum (always)
Quick Reference
| Feature | Example |
|---|---|
| Tailwind styling | class="text-4xl font-bold text-blue-600" |
| Slide backgrounds | data-background-color="#1e293b" (alternate #0f172a) |
| Code blocks | <code class="language-python text-base" data-trim> |
| Speaker notes | <aside class="notes"><p><strong>Topic (60s):</strong></p><ul>...</ul></aside> |
| Fragments | <li class="fragment">Item</li> (build complexity, not click fatigue) |
| Multi-column | <div class="grid grid-cols-2 gap-8"> |
| Semantic colors | Green=good, Red=bad, Yellow=warning, Blue=neutral |
| Typography scale | Code >= body text (text-base min for code, text-xl for body) |
| Auto-animate | Same data-id across slides |
| Overview mode | Press ESC/O |
Essential Configuration
Reveal.initialize({
slideNumber: 'c/t',
hash: true,
width: '100%',
height: '100%',
transition: 'slide',
controls: true,
progress: true,
keyboard: true,
overview: true,
plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ]
});
Workflow
STEP 0: Pre-flight check (above) - refactor if needed
- Set up Tailwind if not present
- Plan structure: horizontal (main) vs vertical (detail)
- Content on slides: high-level only
- Add formatted speaker notes with timing markers to ALL slides
- Detail in notes, not on slides
- Add effects LAST (only where they serve purpose)
- Verify rendering:
- Code examples: Syntax highlighting works,
text-baseortext-lgsizing (never smaller than body text) - Fragments: Progressive reveal works as intended, no "click fatigue"
- Multi-column: Grid layouts don't overflow or break
- Speaker notes: Detailed with timing markers for every slide
- Colors: Semantic meaning clear (green=good, red=bad), sufficient contrast, symbols complement colors
- Typography: Heading hierarchy consistent, code >= body text size
- Code examples: Syntax highlighting works,
Common Rationalizations (STOP)
| If you think... | Reality |
|---|---|
| "Maintain visual consistency" with inline styles | STOP. Refactor to Tailwind |
| "Avoid introducing complexity" | STOP. Bad code IS complex |
| "Original didn't use Tailwind" | STOP. Refactor anyway |
| "This transition draws attention" | STOP. Define actual communication goal |
| "Slide structure guides narrative" | STOP. Add speaker notes anyway |
| "User asked for it quickly" | STOP. Refactoring is faster than tech debt |
| "Code will be readable at default size" | STOP. Set text-base or text-lg explicitly - never smaller than body text |
| "Presenter can ad-lib this section" | STOP. Add detailed speaker notes with timing markers anyway |
| "Need to show complete code example" | STOP. Split into 3-8 line chunks across slides with fragments |
| "Text-sm fits more code in two columns" | STOP. Use text-base, reduce code lines, or make columns wider |
| "Speaker notes take too long to write" | STOP. 3-5x detail ratio is mandatory - saves presenter time during talk |
| "Fragments on everything make it interactive" | STOP. Causes click fatigue - use only for building complexity |
| "Monospace is more readable at smaller sizes" | STOP. Code must be >= body text size - non-negotiable |
| "Balance readability and space" | STOP. Reduce code lines or use larger body text - code size is fixed |
| "Code slightly smaller is fine" | STOP. NO EXCEPTIONS - code >= body text always |
Accessibility Checklist
- Semantic HTML (heading hierarchy)
- Keyboard navigation (Tab, arrows, ESC)
- Speaker notes provide context
- Color contrast sufficient
- No information by color alone
- Alt text for images