tsaol/awesome-claude/html-ppt

HTML PPT Skill

Invoke with #html-ppt + your topic. Generates a single-file HTML deck with zero dependencies.

Reference samples:

- GlobalOperation/growth/amazon-growth-design-rehearsal.html

- GlobalOperation/growth/amazon-growth-design-walkthrough.html

- presentations/html/agent_review_slide.html

Positioning

Not reveal.js / Slidev / Spectacle. A hand-crafted single HTML file — zero dependencies, zero network, double-click to open.

Good for: rehearsal, internal sharing, offline presentations, one-shot decks. Not for: complex animations, React components, long-term team maintenance. Use #reveal-ppt for those.

Detect Mode

Determine what the user wants:

• Mode A: New Presentation — Create from scratch. Go to Step 1.
• Mode B: PPT Conversion — Convert a .pptx file. Go to PPT Conversion section.
• Mode C: Enhancement — Improve an existing HTML presentation. Follow Mode C rules below.

Mode C: Modification Rules

When enhancing existing presentations, viewport fitting is the biggest risk:

1. Before adding content: Count existing elements, check against density limits
2. Adding images: Must have max-height: min(50vh, 400px). If slide already has max content, split into two slides
3. Adding text: Max 4-5 bullets per slide. Exceeds limits? Split into continuation slides
4. After ANY modification, verify: .slide has overflow: hidden, new elements use clamp(), images have viewport-relative max-height, content fits at 1280x720
5. Proactively reorganize: If modifications will cause overflow, automatically split content and inform the user. Don't wait to be asked

When adding images to existing slides: Move image to new slide or reduce other content first. Never add images without checking if existing content already fills the viewport.

Core Principles

1. Zero Dependencies — Single HTML file, all CSS/JS inline. No npm, no CDN.
2. Viewport Fitting (NON-NEGOTIABLE) — Every slide MUST fit exactly in 100vh. No scrolling within slides. Content overflows? Split into multiple slides.
3. Distinctive Design — Avoid generic "AI slop." Choose fonts and colors that feel custom-crafted.
4. Show, Don't Tell — When user is unsure of style, generate visual previews (save to ~/tmp/slide-previews/).

Required Slide Structure

Every deck (slide-deck or rehearsal) MUST include these slides:

These four slides are non-negotiable. The content slides go between Agenda and Takeaway.

Minimum deck structure: Cover → Agenda → [Content slides] → Takeaway → Thank You

Viewport Fitting Rules

These apply to EVERY slide:

• Every .slide must have height: 100vh; height: 100dvh; overflow: hidden;
• ALL font sizes and spacing must use clamp(min, preferred, max) — never fixed px alone
• Include the full contents of viewport-base.css in every presentation
• Include prefers-reduced-motion support
• Never negate CSS functions directly (-clamp() is silently ignored) — use calc(-1 * clamp(...))

Content Density Limits Per Slide

Content exceeds limits? Split into multiple slides. Never cram, never scroll.

Your Task

When user invokes #html-ppt:

Step 1: Confirm Intent

Ask (if not already specified):

1. Topic / content — What is this about?
2. Deck type:

• rehearsal — Speaker notes in dark right panel, timer (N to toggle notes, T for timer)
• walkthrough — Scrollable long-page document (no pagination)
• slide-deck — Multi-page presentation with keyboard navigation
• single-slide — Single 1280x720 poster slide

1. Target audience — Self / team / client (determines tone)
2. Slide count / sections — Default: 8-12 slides

If user says "up to you", default to slide-deck + 8-12 slides.

Step 2: Choose Style

Ask user's style preference:

Option A: Amazon Brand — Orange + dark blue, professional corporate. Skip to Step 3. Option B: Pick a preset — Choose from 12 curated presets directly. See STYLE_PRESETS.md. Option C: Show me options (recommended for custom) — Generate 3 visual previews based on mood.

"Show me options" flow:

1. Ask the mood: Impressed/Confident | Excited/Energized | Calm/Focused | Inspired/Moved
2. Based on mood, pick 3 presets from the mood-to-preset table in STYLE_PRESETS.md
3. Generate 3 single-slide HTML preview files (one per preset) showing title slide with typography, colors, animation
4. Save previews to ~/tmp/slide-previews/ (style-a.html, style-b.html, style-c.html)
5. Open each preview for the user
6. Ask which they prefer: Style A / Style B / Style C / Mix elements

Each preview should be ~50-100 lines, self-contained, showing one animated title slide with the preset's exact fonts, colors, and signature elements.

"Pick a preset" flow:

User names a preset directly (e.g., "Bold Signal", "Neon Cyber"). Read STYLE_PRESETS.md for specs and generate using those exact fonts, colors, and signature elements.

If user says "up to you" or doesn't specify, default to Amazon Brand.

Step 3: Amazon Brand Style (when applicable)

Colors (required for Amazon brand):

• #FF9900 — Amazon orange, accent / highlight / numbers
• #c45500 — Deep orange, eyebrow / tag text
• #232F3E — Amazon dark blue, headings / dark backgrounds
• #FFF8EE — Light orange background for layers/quotes
• #FFE0B2 — Orange borders
• #fff / #1a1a1a / #333 / #555 / #666 / #888 / #ccc — Neutral scale

Font:

font-family: -apple-system, 'PingFang SC', 'Microsoft YaHei', 'Segoe UI', sans-serif;

Top 6px gradient bar (every deck must have):

.top-bar { height: 6px; background: linear-gradient(90deg, #FF9900 0%, #232F3E 100%); }

Border radius: 8px / 10px / 12px only.

Font size ladder:

• Cover H1: 56px → clamp(2rem, 5vw, 3.5rem)
• H2: 44px → clamp(1.5rem, 3.5vw, 2.75rem)
• Body: 22px → clamp(0.9rem, 1.8vw, 1.375rem)
• Punch-line: 60-64px → clamp(2.5rem, 6vw, 4rem)
• Eyebrow: 13px, uppercase, letter-spacing 2px

Step 4: Layout Building Blocks

Do not invent new layouts. Mix these blocks.

Step 5: Interaction Layer (slide-deck and rehearsal)

// Required:
// ← / → / Space / PageDown: next/prev
// Home / Esc: first slide
// End: last slide
// Click: next slide (except on controls/dots)
// Nav dots (right side, active dot highlights on slide change, clickable)
// Progress bar (top 2px, proportional fill)
// Page counter (1 / N)
// Rehearsal additional:
// N: toggle speaker notes
// T: start/stop timer
// R: reset timer

Step 6: Speaker Notes (rehearsal only)

Each slide's notes must include:

1. How to say it — Opening sentence for this slide
2. Key pauses — Where to stop, where to emphasize
3. Potential questions — What the audience might ask
4. Red lines — What NOT to say on this slide

Step 7: Output

Generate the complete HTML file directly. Naming:

• <topic>-rehearsal.html
• <topic>-walkthrough.html
• <topic>-deck.html
• <topic>-slide.html

After generation, give the user an open command and usage tips (keys, notes).

Image Handling

When user provides images for the presentation:

Step 1: Evaluate Images

1. Scan — List all image files (.png, .jpg, .svg, .webp)
2. View each image — Use the Read tool (Claude is multimodal)
3. Evaluate — For each: what it shows, USABLE or NOT USABLE (with reason), dominant colors
4. Co-design the outline — Images inform slide structure alongside text. Don't "plan slides then add images" — design around both from the start

Step 2: Process Images

from PIL import Image, ImageDraw
# Circular crop (for logos on rounded aesthetics)
def crop_circle(input_path, output_path):
    img = Image.open(input_path).convert('RGBA')
    w, h = img.size
    size = min(w, h)
    left, top = (w - size) // 2, (h - size) // 2
    img = img.crop((left, top, left + size, top + size))
    mask = Image.new('L', (size, size), 0)
    ImageDraw.Draw(mask).ellipse([0, 0, size, size], fill=255)
    img.putalpha(mask)
    img.save(output_path, 'PNG')
# Resize (for oversized images)
def resize_max(input_path, output_path, max_dim=1200):
    img = Image.open(input_path)
    img.thumbnail((max_dim, max_dim), Image.LANCZOS)
    img.save(output_path, quality=85)

Step 3: Place Images in HTML

.slide-image {
    max-width: 100%;
    max-height: min(50vh, 400px);
    object-fit: contain;
    border-radius: 8px;
}
.slide-image.screenshot {
    border: 1px solid rgba(255, 255, 255, 0.1);
    border-radius: 12px;
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
}
.slide-image.logo {
    max-height: min(30vh, 200px);
}

Rules:

• Use relative file paths (not base64) for images unless embedding a single logo
• Never repeat the same image on multiple slides (except logos on title + closing)
• Adapt border/shadow colors to match the chosen style's accent
• Logo: centered on title slide. Screenshots: two-column layout with text

PPT Conversion

When user provides a .pptx file:

1. Run python scripts/extract-pptx.py <input.pptx> <output_dir> (install python-pptx if needed)
2. Show extracted slide titles and image counts for confirmation
3. Ask for style preference (Amazon brand or custom)
4. Generate HTML preserving all text, images, and notes

PDF Export

After generating a deck, offer PDF export:

bash scripts/export-pdf.sh <path-to-html> [output.pdf] [--compact]

• Uses Playwright to screenshot each slide at 1920x1080
• --compact flag renders at 1280x720 for smaller files
• Animations are not preserved (static snapshots)

Deploy (Vercel)

After generating a deck, offer deployment for sharing:

bash scripts/deploy.sh <path-to-html>