Frontend Slides

Frontend Slides

Create zero-dependency, animation-rich HTML presentations that run entirely in the browser.

Core Principles

1. Zero Dependencies — Single HTML files with inline CSS/JS. No npm, no build tools.
2. Show, Don't Tell — Generate visual previews, not abstract choices. People discover what they want by seeing it.
3. Distinctive Design — No generic "AI slop." Every presentation must feel custom-crafted.
4. Viewport Fitting (NON-NEGOTIABLE) — Every slide MUST fit exactly within 100vh. No scrolling within slides, ever. Content overflows? Split into multiple slides.

Design Aesthetics

You tend to converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.

Focus on:

• Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.
• Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.
• Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.

Avoid generic AI-generated aesthetics:

• Overused font families (Inter, Roboto, Arial, system fonts)
• Cliched color schemes (particularly purple gradients on white backgrounds)
• Predictable layouts and component patterns
• Cookie-cutter design that lacks context-specific character

Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!

Narrated vs Self-Read — Progressive Disclosure

A deck meant to be narrated (a live talk, a screen-recorded walkthrough) and one meant to be self-read are different artifacts — and the difference changes how content should appear.

• Self-read: the reader sets their own pace. Put everything for a slide on the slide at once.
• Narrated: the speaker sets the pace. The deck should behave like a controllable surface that follows the narration — not a wall of content revealed all at once.

For narrated decks, design for four dimensions of control. Each is a principle, not a prescribed component — implement whatever fits the specific deck:

• Pacing — reveal content in step with the narration (e.g. list items, cards, or steps appear one at a time as the speaker advances), so the audience never reads ahead of the voice.
• Focus — make salient only what is being discussed now (e.g. spotlight the active part of a diagram, dim the rest).
• Depth — keep supporting detail off the main line, available on demand (e.g. an optional popup the speaker opens when a term needs unpacking), so the slide stays uncluttered.
• Structure — keep the deck's macro-skeleton visible (e.g. a small persistent marker of where this slide sits in the overall argument), so the audience holds the thread.

The throughline: at any moment, show only what is relevant right now. Decide per deck which dimensions are worth building — a short talk may need none; a dense teaching walkthrough benefits from all four. Build them fresh each time, sized to the content; do not ship a fixed widget.

Viewport Fitting Rules

These invariants apply to EVERY slide in EVERY presentation:

• Every .slide must have height: 100vh; height: 100dvh; overflow: hidden;
• ALL font sizes and spacing must use clamp(min, preferred, max) — never fixed px/rem
• Content containers need max-height constraints
• Images: max-height: min(50vh, 400px)
• Breakpoints required for heights: 700px, 600px, 500px
• Include prefers-reduced-motion support
• Never negate CSS functions directly (-clamp(), -min(), -max() are silently ignored) — use calc(-1 * clamp(...)) instead

When generating, read viewport-base.css and include its full contents in every presentation.

Content Density Limits Per Slide

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

Phase 0: Detect Mode

Determine what the user wants:

• Mode A: New Presentation — Create from scratch. Go to Phase 1.
• Mode B: PPT Conversion — Convert a .pptx file. Go to Phase 4.
• Mode C: Enhancement — Improve an existing HTML presentation. Read it, understand it, enhance. Follow Mode C modification 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-6 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.

Phase 1: Content Discovery (New Presentations)

Ask ALL questions in a single AskUserQuestion call so the user fills everything out at once:

Question 1 — Purpose (header: "Purpose"): What is this presentation for? Options: Pitch deck / Teaching-Tutorial / Conference talk / Internal presentation

Question 2 — Length (header: "Length"): Approximately how many slides? Options: Short 5-10 / Medium 10-20 / Long 20+

Question 3 — Content (header: "Content"): Do you have content ready? Options: All content ready / Rough notes / Topic only

Question 4 — Inline Editing (header: "Editing"): Do you need to edit text directly in the browser after generation? Options:

• "Yes (Recommended)" — Can edit text in-browser, auto-save to localStorage, export file
• "No" — Presentation only, keeps file smaller

Remember the user's editing choice — it determines whether edit-related code is included in Phase 3.

Question 5 — Delivery (header: "Delivery"): Will this deck be narrated, or read on its own? Options:

• "Narrated walkthrough" — a live talk or screen-recorded video; the speaker paces the audience
• "Self-read" — the reader opens it alone and paces themselves
• "Both"

If the deck is narrated, apply Progressive Disclosure (see above) in Phase 3 — pace the reveal to the narration rather than showing each slide's content all at once.

If user has content, ask them to share it.

Step 1.2: Image Evaluation (if images provided)

If user selected "No images" → skip to Phase 2.

If user provides an image folder:

1. Scan — List all image files (.png, .jpg, .svg, .webp, etc.)
2. View each image — Use the Read tool (Claude is multimodal)
3. Evaluate — For each: what it shows, USABLE or NOT USABLE (with reason), what concept it represents, dominant colors
4. Co-design the outline — Curated images inform slide structure alongside text. This is NOT "plan slides then add images" — design around both from the start (e.g., 3 screenshots → 3 feature slides, 1 logo → title/closing slide)
5. Confirm via AskUserQuestion (header: "Outline"): "Does this slide outline and image selection look right?" Options: Looks good / Adjust images / Adjust outline

Logo in previews: If a usable logo was identified, embed it (base64) into each style preview in Phase 2 — the user sees their brand styled three different ways.

Phase 2: Style Discovery

This is the "show, don't tell" phase. Most people can't articulate design preferences in words.

Step 2.0: Style Path

Ask how they want to choose (header: "Style"):

• "Show me options" (recommended) — Generate 3 previews based on mood
• "I know what I want" — Pick from preset list directly

If direct selection: Show preset picker and skip to Phase 3. Available presets are defined in STYLE_PRESETS.md.

Step 2.1: Mood Selection (Guided Discovery)

Ask (header: "Vibe", multiSelect: true, max 2): What feeling should the audience have? Options:

• Impressed/Confident — Professional, trustworthy
• Excited/Energized — Innovative, bold
• Calm/Focused — Clear, thoughtful
• Inspired/Moved — Emotional, memorable

Step 2.2: Generate 3 Style Previews

Based on mood, generate 3 distinct single-slide HTML previews showing typography, colors, animation, and overall aesthetic. Read STYLE_PRESETS.md for available presets and their specifications.

Save previews to .claude-design/slide-previews/ (style-a.html, style-b.html, style-c.html). Each should be self-contained, ~50-100 lines, showing one animated title slide.

Open each preview automatically for the user.

Step 2.3: User Picks

Ask (header: "Style"): Which style preview do you prefer? Options: Style A: [Name] / Style B: [Name] / Style C: [Name] / Mix elements

If "Mix elements", ask for specifics.

Phase 3: Generate Presentation

Generate the full presentation using content from Phase 1 (text, or text + curated images) and style from Phase 2.

If images were provided, the slide outline already incorporates them from Step 1.2. If not, CSS-generated visuals (gradients, shapes, patterns) provide visual interest — this is a fully supported first-class path.

Before generating, read these supporting files:

• html-template.md — HTML architecture and JS features
• viewport-base.css — Mandatory CSS (include in full)
• animation-patterns.md — Animation reference for the chosen feeling

Key requirements:

• Single self-contained HTML file, all CSS/JS inline
• Include the FULL contents of viewport-base.css in the <style> block
• Use fonts from Fontshare or Google Fonts — never system fonts
• Add detailed comments explaining each section
• Every section needs a clear /* === SECTION NAME === */ comment block

Phase 4: PPT Conversion

When converting PowerPoint files:

1. Extract content — Run python scripts/extract-pptx.py <input.pptx> <output_dir> (install python-pptx if needed: pip install python-pptx)
2. Confirm with user — Present extracted slide titles, content summaries, and image counts
3. Style selection — Proceed to Phase 2 for style discovery
4. Generate HTML — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments)

Phase 5: Delivery

1. Clean up — Delete .claude-design/slide-previews/ if it exists
2. Open — Use open [filename].html to launch in browser
3. Summarize — Tell the user:
   • File location, style name, slide count
   • Navigation: Arrow keys, Space, scroll/swipe, click nav dots
   • How to customize: :root CSS variables for colors, font link for typography, .reveal class for animations
   • If inline editing was enabled: Hover top-left corner or press E to enter edit mode, click any text to edit, Ctrl+S to save

Phase 6: Share & Export (Optional)

After delivery, ask the user: "Would you like to share this presentation? I can deploy it to a live URL, export it as a PDF, or save each slide as a standalone image (for TikTok / Xiaohongshu / Instagram carousels)."

Options:

• Deploy to URL — Shareable link that works on any device
• Export to PDF — Universal file for email, Slack, print
• Export as images — Per-slide PNG/JPEG files for social media posts
• Multiple
• No thanks

If the user declines, stop here. If they choose one or more, proceed below.

6A: Deploy to a Live URL (Vercel)

This deploys the presentation to Vercel — a free hosting platform. The link works on any device (phones, tablets, laptops) and stays live until the user takes it down.

If the user has never deployed before, guide them step by step:

1. Check if Vercel CLI is installed — Run npx vercel --version. If not found, install Node.js first (brew install node on macOS, or download from https://nodejs.org).

2. Check if user is logged in — Run npx vercel whoami.

   • If NOT logged in, explain: "Vercel is a free hosting service. You need an account to deploy. Let me walk you through it:"
     • Step 1: Ask user to go to https://vercel.com/signup in their browser
     • Step 2: They can sign up with GitHub, Google, email — whatever is easiest
     • Step 3: Once signed up, run vercel login and follow the prompts (it opens a browser window to authorize)
     • Step 4: Confirm login with vercel whoami
   • Wait for the user to confirm they're logged in before proceeding.

3. Deploy — Run the deploy script:

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

   The script accepts either a folder (with index.html) or a single HTML file.

4. Share the URL — Tell the user:

   • The live URL (from the script output)
   • That it works on any device — they can text it, Slack it, email it
   • To take it down later: visit https://vercel.com/dashboard and delete the project
   • The Vercel free tier is generous — they won't be charged

⚠ Deployment gotchas:

• Local images/videos must travel with the HTML. The deploy script auto-detects files referenced via src="..." in the HTML and bundles them. But if the presentation references files via CSS background-image or unusual paths, those may be missed. Before deploying, verify: open the deployed URL and check that all images load. If any are broken, the safest fix is to put the HTML and all its assets into a single folder and deploy the folder instead of a standalone HTML file.
• Prefer folder deployments when the presentation has many assets. If the presentation lives in a folder with images alongside it (e.g., my-deck/index.html + my-deck/logo.png), deploy the folder directly: bash scripts/deploy.sh ./my-deck/. This is more reliable than deploying a single HTML file because the entire folder contents are uploaded as-is.
• Filenames with spaces work but can cause issues. The script handles spaces in filenames, but Vercel URLs encode spaces as %20. If possible, avoid spaces in image filenames. If the user's images have spaces, the script handles it — but if images still break, renaming files to use hyphens instead of spaces is the fix.
• Redeploying updates the same URL. Running the deploy script again on the same presentation overwrites the previous deployment. The URL stays the same — no need to share a new link.

6B: Export to PDF

This captures each slide as a screenshot and combines them into a PDF. Perfect for email attachments, embedding in documents, or printing.

Note: Animations and interactivity are not preserved — the PDF is a static snapshot. This is normal and expected; mention it to the user so they're not surprised.

1. Run the export script:

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

   If no output path is given, the PDF is saved next to the HTML file.

2. What happens behind the scenes (explain briefly to the user):

   • A headless browser opens the presentation at 1920×1080 (standard widescreen)
   • It screenshots each slide one by one
   • All screenshots are combined into a single PDF
   • The script needs Playwright (a browser automation tool) — it will install automatically if missing

3. If Playwright installation fails:

   • The most common issue is Chromium not downloading. Run: npx playwright install chromium
   • If that fails too, it may be a network/firewall issue. Ask the user to try on a different network.

4. Deliver the PDF — The script auto-opens it. Tell the user:

   • The file location and size
   • That it works everywhere — email, Slack, Notion, Google Docs, print
   • Animations are replaced by their final visual state (still looks great, just static)

⚠ PDF export gotchas:

• First run is slow. The script installs Playwright and downloads a Chromium browser (~150MB) into a temp directory. This happens once per run. Warn the user it may take 30-60 seconds the first time — subsequent exports within the same session are faster.
• Slides must use class="slide". The export script finds slides by querying .slide elements. If the presentation uses a different class name, the script will report "0 slides found" and fail. All presentations generated by this skill use .slide, so this only matters for externally-created HTML.
• Local images must be loadable via HTTP. The script starts a local server and loads the HTML through it (so Google Fonts and relative image paths work). If images use absolute filesystem paths (e.g., src="/Users/name/photo.png") instead of relative paths (e.g., src="photo.png"), they won't load. Generated presentations always use relative paths, but converted or user-provided decks might not — check and fix if needed.
• Local images appear in the PDF as long as they are in the same directory as (or relative to) the HTML file. The export script serves the HTML's parent directory over HTTP, so relative paths like src="photo.png" resolve correctly — including filenames with spaces. If images still don't appear, check: (1) the image files actually exist at the referenced path, (2) the paths are relative, not absolute filesystem paths like /Users/name/photo.png.
• Large presentations produce large PDFs. Each slide is captured as a full 1920×1080 PNG screenshot. An 18-slide deck can produce a ~20MB PDF. If the PDF exceeds 10MB, ask the user: "The PDF is [size]. Would you like me to compress it? It'll look slightly less sharp but the file will be much smaller." If yes, re-run the export with the --compact flag:

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

  This renders at 1280×720 instead of 1920×1080, typically cutting file size by 50-70% with minimal visual difference.

6C: Export as Per-Slide Images

This captures each slide as a separate PNG (or JPEG) image — one file per slide. Perfect for TikTok / Reels / Xiaohongshu / Instagram carousel posts, where each platform wants a sequence of standalone images rather than a single PDF.

1. Run the export script:

   bash scripts/export-images.sh <path-to-html> [output-dir]
   

   If no output directory is given, images go into <deck-name>-images/ next to the HTML file.

2. What happens behind the scenes (explain briefly):

   • Same headless-browser machinery as PDF export
   • Captures each slide at 1920×1080 by default
   • Writes slide-001.png, slide-002.png, … into the output folder
   • Opens the folder automatically when done

3. Choosing a mode — Ask the user where they plan to post:

   Goal	Flag	Output
   Blog headers, IG landscape, raw screenshots	(default)	1920×1080 PNG (desktop layout)
   Smaller file size	--compact	1280×720 PNG (desktop layout)
   TikTok / Reels / Xiaohongshu vertical	--portrait	1080×1920 (deck reflows for mobile)
   Instagram square / Xiaohongshu 1:1	--square	1080×1080 (deck reflows for mobile)
   Smaller files for upload	--format jpeg	JPEG instead of PNG (typically 80–90% smaller)

   Flags combine: --portrait --format jpeg is the typical "TikTok-ready" combo.

   Important: --portrait and --square render the deck at a narrow viewport (540×960 / 540×540) and capture at 2× DPR. This triggers the deck's own responsive CSS (@media (max-width: 600px) rules from viewport-base.css) so the slide reflows for vertical — not letterboxed. For a deck without mobile-responsive CSS, the output will look like a small-window desktop screenshot, not a polished vertical post.

4. Deliver the folder — Tell the user:

   • Folder location, image count, total size
   • That each image is a self-contained post — drag-and-drop into the upload UI
   • For carousels: most platforms accept the files in filename order (slide-001 first)

⚠ Image export gotchas:

• Same dependencies as PDF export. Playwright + Chromium download happens once; subsequent runs are fast.
• Same .slide requirement. The script finds slides via .slide selector.
• Portrait/square modes need a mobile-responsive deck. They render at a phone-sized viewport (540×960 / 540×540) at 2× DPR, relying on the deck's own max-width: 600px media queries to reflow content for vertical. Decks generated by this skill ship with the viewport-base.css mobile patterns (nav-dots bottom bar, multi-col stack, code-block overflow-wrap, etc.) and work out of the box. Externally-authored decks without mobile rules will look like small desktop screenshots.

Supporting Files