html-slides（HTML slides 开发）

HTML Slides — Animated, Viewport-Fitted Presentations

Generate single-file, self-contained HTML presentations with professional animations, responsive viewport fitting, and curated style presets. Zero external dependencies at runtime — all CSS/JS inline.

Architecture

Every HTML presentation follows this structure:

1. Single file — One .html file with inline CSS and JS (no build tools)
2. Viewport fitted — Each slide locks to 100vh/100dvh with overflow: hidden
3. CSS custom properties — All theming via :root variables for easy restyling
4. Semantic HTML — <section> per slide, <nav> for controls
5. Progressive enhancement — Works without JS, animations enhance with JS

Mandatory Viewport Rules

Apply the viewport base CSS from assets/viewport-base.css to EVERY presentation. Key rules:

• Every slide: height: 100vh; height: 100dvh; overflow: hidden
• All typography uses clamp(min, preferred, max) for responsive scaling
• Images constrained to min(50vh, 400px) max height
• Responsive breakpoints at 700px, 600px, 500px heights
• prefers-reduced-motion support included
• Grid fallback: grid-template-columns: repeat(auto-fit, minmax(min(100%, 250px), 1fr))

Never allow scrolling within a slide. If content exceeds capacity, split across multiple slides.

Edge Case: Negative Clamp Values Use calc(-1 * clamp(...)) when you need negative viewport-edge spacing (e.g., negative margins, negative padding). This pattern preserves the clamp function's responsiveness while inverting the value.

iOS Safari 100vh Bug The 100vh unit in iOS Safari includes the address bar, causing content to overflow. Always pair 100vh with 100dvh (dynamic viewport height) in fallback chains. Modern viewports ignore 100vh if 100dvh is present.

Animation System

CSS-First Approach (Default)

Use CSS animations as the baseline. Apply .reveal class with staggered transition-delay:

.reveal {
  opacity: 0;
  transform: translateY(20px);
  transition: opacity 0.6s var(--ease-out-expo), transform 0.6s var(--ease-out-expo);
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}

Trigger with Intersection Observer adding .visible class on viewport entry.

Easing: --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1) for all entrance animations.

GSAP Enhancement (When Requested)

For sophisticated animations, load GSAP from CDN and use timeline-based choreography. Consult references/animation-patterns.md for detailed GSAP recipes and the GSAP docs for API reference. Key integration points:

• Load GSAP + ScrollTrigger from https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js
• Use gsap.timeline() for sequenced slide entrance animations
• Apply gsap.matchMedia() for responsive animation behavior
• Respect prefers-reduced-motion — disable animations when active

Timeline Entrance with Position Parameter Stagger reveals without explicit delays using the position parameter in timeline. Example:

const tl = gsap.timeline();
tl.to('.heading', { opacity: 1, duration: 0.6 })
  .to('.subtitle', { opacity: 1, duration: 0.4 }, '<0.2') // Starts 0.2s before heading ends
  .to('.bullet', { opacity: 1, stagger: 0.1 }, '<0.15');

SplitText for Headlines and Word/Char Reveals Animate individual words or characters in headlines:

gsap.registerPlugin(SplitText);
const split = new SplitText('.headline', { type: 'words,chars' });
gsap.from(split.chars, {
  opacity: 0,
  duration: 0.4,
  stagger: 0.05,
  ease: 'back.out'
});

ScrollTrigger for Slide-by-Slide Navigation Tie slide transitions to scroll position for interactive presentations:

gsap.registerPlugin(ScrollTrigger);
gsap.to('.slide', {
  scrollTrigger: {
    trigger: '.slide-container',
    pin: true,
    scrub: 1,
    snap: 1 / slideCount
  }
});

Spring Physics Timing from Remotion Translate Remotion spring physics into GSAP elastic easing for natural motion:

• Smooth (damping: 200) → elastic.out(1, 0.1) — subtle bounce, feels polished
• Snappy (damping: 20) → elastic.out(1, 0.35) — noticeable spring, modern feel
• Bouncy (damping: 8) → elastic.out(1, 0.5) — playful bounce, energetic

Animation Inventory

Animation Guidelines

• Playful: Bouncy easing, 400-600ms, staggered reveals
• Professional: Subtle fades, 200-300ms, minimal movement
• Cinematic: Slow fades 1-1.5s, parallax, scale transitions
• Technical: Sharp, fast (150-200ms), no bounce

Slide Navigation

Include keyboard navigation (arrows, space, Page Up/Down), touch/swipe support, and optional progress indicator. Template in references/html-template.md.

Style Preset Application

Read style preset definitions from the parent slide-design skill's references/style-presets.md. Each preset maps to CSS custom properties:

:root {
  --bg-primary: #0a0a0a;
  --bg-secondary: #1a1a1a;
  --text-primary: #ffffff;
  --text-secondary: #a0a0a0;
  --accent: #4a9eff;
  --accent-secondary: #ff6b6b;
  --font-heading: 'Clash Display', sans-serif;
  --font-body: 'IBM Plex Sans', sans-serif;
  --title-size: clamp(2rem, 6vw, 5rem);
  --body-size: clamp(0.9rem, 2vw, 1.25rem);
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

Load fonts from Google Fonts or Fontshare — never rely on system fonts for headings.

Slide Type Templates

For each slide type, follow the HTML patterns in references/html-template.md. Key templates:

• Title slide — Full-viewport hero with heading, subtitle, optional background image
• Content slide — Heading + bullet list or paragraphs with staggered reveal
• Two-column — Side-by-side layout with image + text or code + explanation
• Image focus — Full-bleed or centered image with caption overlay
• Code slide — Syntax-highlighted code block with Prism.js (CDN loaded)
• Comparison — Side-by-side cards or before/after layout
• Quote — Centered blockquote with attribution
• Feature grid — CSS Grid cards (max 6) with icons/titles/descriptions
• Timeline — Horizontal or vertical milestone layout

Mermaid Diagram Support

For technical presentations, embed Mermaid diagrams:

1. Include Mermaid CDN: https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.0/mermaid.min.js
2. Use <pre class="mermaid"> blocks for diagrams
3. Support flowcharts, sequence diagrams, class diagrams, and ER diagrams
4. Style with theme variables matching the presentation palette

PDF Export Support

Include an optional print stylesheet for PDF export via browser print:

@media print {
  .slide { page-break-after: always; height: 100vh; }
  .nav, .progress { display: none; }
  .reveal { opacity: 1; transform: none; }
}

Anti-Patterns

Avoid these common mistakes:

• Scrolling within slides (always overflow: hidden)
• System fonts for headings (always load web fonts)
• Generic "AI slop" aesthetics (purple gradients, Inter everywhere)
• Inline styles (use CSS custom properties)
• Missing prefers-reduced-motion support
• Images without size constraints
• More than 6 items in a feature grid

Show Don't Tell

Embody the principle of visual communication. Enhance instructions with visual weight and intentionality:

• "Make it bold" — Pair font weight increase with size increase AND accent color. A truly bold element dominates the hierarchy.
• "Make it stand out" — Combine z-index layering, scale transformation, AND contrasting color simultaneously. Isolation requires all three.
• "One idea per slide" — When content exceeds capacity, split across slides. Never shrink fonts below the minimum size threshold. Cramping is a design failure.
• Visual hierarchy rule: The most important element should be 3x the size of supporting elements. If a headline is 3rem, body text should be ~1rem. Apply this ratio consistently.

Mixed-Background Decks

Many professional presentations alternate background colors across slide groups. To implement this:

• Define a data-theme attribute per <section> (e.g., data-theme="coral", data-theme="dark", data-theme="cream")
• Map each theme to CSS custom property overrides via [data-theme="coral"] {--bg-primary: #E8845C; --text-primary: #fff;}
• Maintain font and layout consistency even when backgrounds change
• Use contrasting backgrounds to signal section transitions (e.g., black for demo sections, cream for infographics)

Inline Edit Mode

Generated HTML can include contenteditable="true" attributes on text elements, allowing users to edit slides directly in the browser before presenting.

To enable inline editing, add contenteditable="true" to text elements:

<h1 contenteditable="true">Edit this headline</h1>
<p contenteditable="true">Edit this paragraph</p>

Include this CSS for visual feedback:

[contenteditable]:hover {
  outline: 2px dashed var(--accent);
  cursor: text;
}

[contenteditable]:focus {
  outline: 2px solid var(--accent);
}

Users can click any editable element, make changes live, and present without exporting. Disable with contenteditable="false" if read-only mode is preferred.

Additional Resources

Reference Files

• references/html-template.md — Complete HTML boilerplate with navigation, all slide type templates
• references/animation-patterns.md — CSS and GSAP animation recipes with timing and easing

Asset Files

• assets/viewport-base.css — Mandatory viewport CSS (include in every presentation)

Script Files

• scripts/extract-pptx.py — Extract text, images, and notes from PPTX files to JSON for HTML conversion