Slide Sage

Create data-rich, interactive HTML presentations as single files with charts, diagrams, and code highlighting.

Core Principles

1. Data-First — Charts, diagrams, and metrics are first-class citizens, not afterthoughts
2. Single File — Every presentation is one HTML file with inline CSS/JS. Libraries from CDN only
3. Viewport Fitting (NON-NEGOTIABLE) — Every slide fits exactly within 100vh. No scrolling. Content overflows? Split into multiple slides
4. Adaptive Intelligence — When given raw data, act as narrative director. When given a clear outline, act as layout executor
5. Colorblind Safe — All data visualization uses accessible color palettes by default
6. Utility-First CSS (NON-NEGOTIABLE) — Define CSS classes in <style> before referencing them in HTML. Never use inline style="..." for properties that repeat across 2+ elements. Read references/css-class-inventory.md for all available classes

Phase 0: Detect Mode

Determine what the user wants:

• Mode A: New Presentation — Create from scratch. Go to Phase 1
• Mode B: PPT/PDF Conversion — User provides a .pptx or .pdf file. Extract content with scripts/extract-pptx.py or scripts/extract-pdf.py, then treat extracted JSON as input for Mode A
• Mode C: Enhancement — User references an existing HTML file. Read it first, understand its style and structure, then add/modify slides while preserving consistency

Mode C Rules

When enhancing existing presentations:

1. Read the existing HTML file completely before making changes
2. Match the existing style preset, fonts, colors, and animation level
3. Check content density before adding — respect slide type limits
4. If modifications cause overflow, split into additional slides automatically
5. Preserve all existing speaker notes and keyboard navigation

Phase 1: Smart Interview

Goal: Always confirm key decisions with the user before generating — even when the prompt is detailed.

Always-Ask Questions (mandatory, every presentation)

Always ask these two questions together in a single message, regardless of how much detail the user provides:

Question 1 — Audience & Purpose:

"Who is the audience? (e.g., investors, engineers, students, general)"

Question 2 — Style:

"Any style preference? I have 6 presets: - Arctic Dawn — Cool blues, clean (science/research) - Ember — Warm on dark, high contrast (dashboards/metrics) - Jade Circuit — Green/gold on charcoal (engineering/architecture) - Dusk Palette — Muted purple/pink (creative/design) - Monochrome Pro — Grayscale + accent (executive/formal) - Ocean Deep — Navy, aqua, coral (corporate/professional) - Or tell me your brand colors for a custom theme"

If the user already specified audience and style in their prompt, acknowledge their choices and confirm: "I'll use [audience] targeting with [preset]. Sound good?"

Conditional Questions (only when info is missing)

After the always-ask questions, add any of these that apply:

Never ask about: animation level (detect from audience), library choices (auto-select), file format (auto-detect), presenter mode (default to comment notes).

Outline Confirmation (for large presentations)

If the planned presentation has more than 15 slides, present a brief slide outline before generating:

"Here's the planned structure ([N] slides): 1. Title 2. Agenda 3-5. [Section name] ... [N]. Closing

>

Does this look right, or should I adjust?"

For 15 slides or fewer, skip the outline confirmation and proceed directly to Phase 2.

Phase 2: Content Analysis

Analyze the user's content to determine what's needed.

Detect Content Types

Scan the user's message for:

Library Selection (Silent)

Based on content types, decide which CDN libraries to include. Do NOT ask the user — just select:

Default: If the presentation has only text, include NO extra libraries. CSS animations suffice.

Detect Animation Level

Detect File Format

• Less than 3 small images → Single HTML file (images as data URIs)
• Many images or large images → HTML file + assets/ folder

Phase 3: Style Selection

Read references/style-guide.md for the full style system.

Three-Tier System

Tier 1: Data-Viz Palettes — Always applied. Colorblind-safe chart colors regardless of aesthetic choice.

Tier 2: Named Presets — If user didn't specify a style, choose based on content:

Tier 3: Custom Theme — If user provides brand colors, generate a custom theme using the theme builder algorithm.

Style Application

1. Set CSS custom properties on :root from the chosen preset
2. Apply Google Fonts from the preset
3. Set chart color palette from the preset's chart colors
4. Apply light or dark mode based on preset defaults (user can override)

Phase 4: Generate Presentation

Step 1: Read Required References

Always read:

• references/html-template.md — Base HTML structure, SlidePresentation class
• references/viewport-system.md — Responsive CSS rules
• assets/viewport-base.css — Core CSS to inline
• references/css-class-inventory.md — Available CSS classes and inline style rules

Conditionally read (based on Phase 2 analysis):

• references/viz-integration.md — If charts/data
• references/diagram-patterns.md — If architecture/flow diagrams
• references/animation-guide.md — For animation patterns at detected level
• references/code-highlighting.md — If code snippets
• references/presenter-mode.md — If user explicitly requests presenter view

Step 2: Plan Slide Structure

Before generating, plan the slide deck:

1. Title slide — Presentation title, subtitle, date/author
2. Agenda/Overview slide — If 8+ slides
3. Content slides — One concept per slide, respect density limits:

• Title: 1 heading + 1 subtitle
• Content: 1 heading + 4-6 bullets OR 2 short paragraphs
• Chart: 1 heading + 1 chart (max 55vh height) + optional caption
• Code: 1 heading + 10-12 lines of code
• Diagram: 1 heading + 1 diagram (max 60vh)
• Comparison: 1 heading + 2 columns
• Quote: 1 quote (max 3 lines) + attribution
• Image: 1 heading + 1 image (max-height: min(50vh, 400px))

1. Key takeaway / Summary slide — If 8+ slides
2. Closing slide — Thank you, contact, or call to action

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

Step 3: Generate HTML

Structure the HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Presentation Title]</title>
  <link href="[Google Fonts URL]" rel="stylesheet">
  <style>
    /* viewport-base.css (inlined) */
    /* Chosen style preset CSS variables */
    /* Animation keyframes for detected level */
    /* Code theme CSS (if code slides) */
    /* Prism.js theme (if code slides) */
  </style>
</head>
<body>
  <div class="slides-container">
    <div class="slide" id="slide-1">
      <div class="slide-content">
        <!-- Slide content -->
      </div>
      <!-- NOTES: Speaker notes here -->
    </div>
    <!-- More slides -->
  </div>

  <div class="progress-bar"><div class="progress-fill"></div></div>
  <div class="slide-counter"></div>

  <!-- CDN libraries (only those needed) -->
  <script src="[Chart.js CDN if needed]"></script>
  <script src="[Prism.js CDN if needed]"></script>

  <script>
    // SlidePresentation class (from html-template.md)
    // Chart initializations
    // Diagram template rendering
    // Prism.highlightAll() — MUST call after DOM ready
  </script>
</body>
</html>

Step 4: Chart Generation

When creating charts, follow these rules:

1. Use Chart.js as default (covers 80% of chart needs)
2. Place canvas in a responsive container: max-height: min(55vh, 420px)
3. Apply colorblind-safe palette from Tier 1
4. Match chart text colors to the presentation theme
5. Set animation based on detected level (minimal → animation: false)
6. Max 2 charts per slide in a side-by-side flexbox layout
7. Include axis labels and a legend where appropriate

Step 5: Diagram Generation

Use a CSS-first approach for all diagrams.

Tier 0: CSS/HTML Diagrams (PREFERRED — use for 80% of diagrams)

Styled divs with flexbox/grid, borders, and accent colors. Full theme integration, perfect sizing, zero dependencies. Use the utility classes from viewport-base.css:

• Sequence flows → .sequence-flow, .seq-participants, .seq-actor, .seq-step, .seq-arrow
• Architecture stacks → .arch-stack, .arch-row, .arch-row-group
• Pyramids/hierarchies → .pyramid, .pyramid-layer
• Process flows → .process-flow, .process-step, .process-arrow
• Comparisons → .card-accent, .card-top-accent with CSS Grid

See references/diagram-patterns.md Tier 0 for complete HTML patterns.

Tier 1: SVG Templates — If the diagram matches a common pattern, use a pre-designed SVG template from templates/diagrams/. Available: microservices, data-pipeline, client-server, layered-arch, cicd-pipeline, hub-and-spoke, cloud-three-tier, kubernetes-cluster, event-driven-pubsub, ml-pipeline, c4-context, network-zones, api-gateway-auth, pyramid-roadmap, funnel, nested-scopes, tree-hierarchy. Write only the data object (~200-400 chars)

Tier 2: Inline SVG — Only for fully custom diagrams needing precise geometry (network topologies, custom shapes). Use viewBox + preserveAspectRatio + CSS variables for colors. Never use raw coordinate math for arrows — use CSS borders or SVG <marker> with clean polygon definitions.

For diagram style:

• Clean geometric (default) — Rounded corners, soft colors, professional
• Hand-drawn (user opts in) — Apply Rough.js to shapes for sketch-style

Step 5b: Icon Integration

When slides reference specific technologies or infrastructure components, enhance visual recognition with icons from the curated Lucide icon set.

When to use icons:

• Architecture diagrams mentioning specific tech (database, cloud, auth, server)
• Process steps or workflow slides where icons aid scanning
• KPI/metric cards where a category icon adds context
• Bullet lists with technical items (optional, don't overuse)

How to include:

1. Read references/icon-library.md for the full icon catalog and path data
2. Include the hidden sprite block from templates/icons/lucide-sprite.svg at the top of <body> (before slides)
3. Reference icons via <use href="#icon-name"> inside inline SVG diagrams
4. Or use standalone <svg class="icon"> elements in HTML slide content

Icon sizing:

• In SVG diagrams: width="20" height="20" for standard boxes, width="16" height="16" for small contexts
• In HTML content: use the .icon CSS class (1.2em, inherits text color)

Rules:

• Icons are always optional — never required. Templates work perfectly without them
• Only include the sprite block when at least one slide uses icons (don't add unused dependencies)
• Icons inherit currentColor — they automatically match the presentation theme
• Prefer icons that reinforce the component's function: database→database, auth→shield, API→plug, cloud→cloud

Step 6: Comparison Slides

When content involves comparisons (before/after, pros/cons, A vs B):

• Use split-view layout from templates/comparison/split-view.html
• Or feature matrix from templates/comparison/feature-matrix.html
• Color-code columns with accent and secondary accent colors

Step 7: Visual Polish (Applied by Default)

Apply visual depth techniques based on the detected animation level. These are on by default — not optional extras.

How to apply:

1. Add bg-grid class to .slides-container for Balanced/Dramatic levels
2. Add reveal class to content elements inside slides (cards, list items, diagram blocks) for Balanced/Dramatic
3. Add card-accent or card-top-accent to card elements
4. Use badge classes for labels, step numbers, and status indicators
5. Add glow to key accent elements for Dramatic level
6. Use tight-heading on main headings for tighter letter-spacing
7. Use inline-code class for short code references in text (e.g., FallbackModel(...))

See references/style-guide.md "Visual Depth Techniques" section for full details.

Step 8: Code Slide Quality

When generating code slides:

1. Always specify the language class on <code> elements: <code class="language-python">
2. Call Prism.highlightAll() in the initialization script after DOM ready
3. Max 10-12 lines per code block — if more, split across slides
4. For inline code references (like FallbackModel(...) in a paragraph), use <code class="inline-code"> — do NOT create a separate code block
5. Style code containers with proper padding, border-radius, and a code-appropriate background

See references/code-highlighting.md for Prism.js initialization requirements.

Phase 5: Deliver

Pre-Delivery Validation (MANDATORY)

Before writing the final HTML file, perform these checks. This takes 30 seconds and prevents silent visual regressions.

#### Check 1: Class Integrity

Scan every class="..." attribute in the generated HTML. For each class name:

• Is it in viewport-base.css? → OK
• Is it in a comparison template you used? → OK
• Is it defined in this presentation's <style> block? → OK
• Is it a standard class from a CDN library (e.g., Prism.js)? → OK
• None of the above? → BUG. Define the class in <style> or use the correct existing class name.

Common traps:

#### Check 2: Inline Style Audit

Count style=" occurrences across all slides. Calculate per-slide average.

• Target: max ~3 inline styles per slide average
• If over threshold: Identify repeating patterns and extract to CSS classes
• Common offenders: style="color: ...", style="font-size: ...", style="display: flex; gap: ..."

#### Check 3: Repeating Pattern Detection

Search for any inline style value that appears on 3+ elements. Extract to a class:

• Three style="font-size: 0.85rem; color: rgba(255,255,255,0.6)" → .muted-text class
• Four style="display: flex; gap: 1rem; align-items: center" → .flex-row .gap-md or custom class
• Multiple style="background: rgba(255,255,255,0.05); border-radius: 8px; padding: 1rem" → .surface-card class

#### Check 4: Theme Variable Usage

Verify that custom CSS classes use theme variables, not hard-coded values:

• Colors: var(--color-accent) not #89b4fa
• Spacing: var(--spacing-md) not 1.25rem
• Fonts: var(--font-mono) not 'JetBrains Mono'
• Radius: var(--radius) not 12px

This ensures the presentation respects the chosen theme and can be re-themed by changing :root variables.

Output

1. Write the HTML file to the user's specified path (or suggest a reasonable filename like presentation.html)
2. Briefly mention:

• How to open: "Open in any browser"
• Keyboard shortcuts: "Use arrow keys to navigate, '?' for help"
• PDF export: "Print > Save as PDF for a printable version"
• Presenter mode: "Press 'P' for presenter view with speaker notes"

1. Note the tech stack used: "Built with [Chart.js, Prism.js] via CDN"

Do NOT

• Do NOT ask for approval before writing the file — just generate it
• Do NOT explain every design decision — the user wants a presentation, not a design document
• Do NOT include unused libraries — only CDN scripts that are actually referenced

Data Input Handling

Inline Data

If the user provides numbers in their message, extract and structure them:

• "Revenue went from $2.1M to $2.8M" → bar/line chart data
• Table of values → appropriate chart type
• Percentages → pie/doughnut or bar chart

JSON/CSV Data

If the user pastes or references structured data:

1. Parse the structure
2. Identify what maps to labels vs values
3. Choose the best chart type for the data shape
4. Generate the chart configuration

Data Description

If the user describes data without specific numbers:

• Use representative/realistic example data
• Note in speaker notes: "Sample data — replace with actual values"

Viewport Fitting — Critical Rules

These apply to EVERY slide in EVERY presentation:

• .slide has height: 100vh; height: 100dvh; overflow: hidden;
• ALL font sizes use clamp(min, preferred, max) — never fixed px/rem
• Images: max-height: min(50vh, 400px); width: auto; object-fit: contain;
• Charts: container max-height: min(55vh, 420px)
• Diagrams: container max-height: min(60vh, 450px)
• Code blocks: max-height: min(55vh, 400px); overflow: hidden;
• Include height breakpoints: @media (max-height: 700px), 600px, 500px
• Include prefers-reduced-motion support
• Never negate CSS functions directly — use calc(-1 * clamp(...))

If content doesn't fit → split into multiple slides. Never scroll.

Inline Style Rules — Critical

These rules prevent the #1 cause of post-generation cleanup.

When Inline Styles Are ACCEPTABLE

• One-off positioning: A single element needs position: absolute; top: 15%; left: 60%
• Animation delays: style="--stagger-index: 3" or style="animation-delay: 0.3s"
• Dynamic computed values: Chart container heights that depend on data count
• SVG presentation attributes: fill, stroke, transform inside <svg> elements

When Inline Styles Are FORBIDDEN

• Font size, color, padding, margin, gap, display — Always use a class
• Any property on 2+ elements — If you write the same style twice, make it a class
• Background colors on cards/containers — Use a class with theme variable
• Typography styling (font-family, font-weight, text-transform, letter-spacing) — Always a class

The 3-Strike Rule

Before writing style="..." on an element, check:

1. Does this property appear on any other element? → Make a class
2. Is this a standard layout property (display, flex, grid, gap, padding, margin)? → Make a class
3. Could this be expressed with a theme variable? → Make a class

If all three answers are "no", the inline style is acceptable.

Generation Workflow for Custom Slide Types

When creating a new slide type (metric cards, section headers, tech stack grids, etc.):

1. Define the CSS class(es) in `<style>` first
2. Use theme variables (var(--color-accent), var(--spacing-md), etc.)
3. Apply the class in HTML
4. If multiple visual variants needed, use modifier classes (.card.highlight, .step.active)

Accessibility

• Colorblind-safe palettes for ALL data visualization (Tier 1 always active)
• Semantic HTML: proper heading hierarchy, alt text for images
• Keyboard navigation: full keyboard support, visible focus indicators
• prefers-reduced-motion: disable all animations and transitions
• @media print: clean print output, one slide per page
• Sufficient color contrast (WCAG AA minimum)
• aria-label on interactive elements (chart canvases, nav buttons)

Cross-Platform Notes

This skill works across AI coding tools. Some capabilities vary:

• WebFetch available (Claude Code, Gemini CLI): Can verify CDN URLs are current
• WebFetch unavailable (Codex CLI, Cursor): Use the pinned CDN URLs above — they are stable
• Subagents available (Claude Code): Can parallelize chart research and generation
• Subagents unavailable (most tools): Sequential generation works fine
• Bash available (all): Required for PPT conversion scripts and image processing
• File reading (all): Required for Mode C (enhancement) and reference file loading