html-slides

---
name: html-slides
description: >
  Create stunning single-file HTML presentations (slides) with responsive auto-scaling,
  keyboard navigation, and Chart.js integration. Use this skill whenever the user asks to create slides,
  presentations, slide decks, or HTML-based pitch decks — even if they don't explicitly say "slides".
  Also use when they mention converting content into a visual presentation format, making a talk visually
  compelling, or building an interactive slideshow. Supports 12 curated color palettes (6 dark + 6 light)
  sourced from ColorHunt, deliberately avoiding the overused tech blue-purple palette. Dark palettes:
  Amber Gold, Deep Teal, Crimson Night, Forest Shadow, Silver Elite, Volcanic Orange. Light palettes:
  Paper Navy, Cloud Teal, Warm Terracotta, Lavender Mist, Sage Garden, Blush Coral.
---

# HTML Slides Builder

Build a single-file HTML presentation that opens in any browser, auto-scales to fit any screen, and looks like it was designed by a professional studio — not a template factory.

## Why this approach works

One HTML file means zero dependencies, zero build steps, zero "it works on my machine." You double-click it and present. The fixed 1920x1080 design stage auto-scales to any viewport, so it always looks pixel-perfect whether you're on a laptop or a projector. Chart.js handles data viz inline. Everything — style, markup, scripts — lives in one file.

## Recommended workflow

Follow this end-to-end flow for the best results. Each step builds on the previous one, and the user gets review opportunities at every stage.

### Step 1: Gather requirements, fit intent, and generate text draft

When the user describes their presentation needs, first produce a **text-only draft** — an outline of what each slide should say, organized by slide number. Include: slide titles, bullet points, key metrics, chart descriptions, speaker assignments, and a **layout budget** for each slide. This gives the user something concrete to review before any visual work begins.

Present the draft in a structured format:
```
Slide 1 (Cover): Title / Subtitle / Team members
Slide 2 (Part Divider): Part 1 — [Section] / Speaker: [Name]
Slide 3 (Chart + Metrics): [Title] — Key data points, metrics to highlight
...
```

For every slide in the draft, add a short budget note such as:
- `Title budget: <= 10 words`
- `Body budget: <= 4 bullets or <= 45 words`
- `Card budget: 3 cards max`
- `Chart density: exact numeric / conceptual / none`

Wait for the user to review and approve the draft. They may adjust content, add data, or restructure the flow.

### Step 2: Run the pattern fit checklist

Before collecting assets or generating HTML, decide whether each slide is actually using the right pattern.

Pattern fit checklist:
- Is this an **information-dense** slide or a **statement** slide?
- Does it need a **horizontal** structure, **vertical** stack, or a true **grid**?
- Should date, team, logo, CTA, or contact blocks be removed instead of merely shrunk?
- Is this better as a recurring academic pattern than a generic pitch-deck layout?
- If the same slide needs 3 structural tweaks later in the debugger, stop micro-tuning and refit the pattern.

### Step 3: Collect assets

Before generating the HTML, gather any assets the user wants to include:
- **Images** — screenshots, logos, diagrams. Convert to base64 for single-file embedding.
- **Chart data** — exact numbers, labels, datasets.
- **Logo** — if they want a corner logo, get the image file.

The configurator (`assets/slide-builder.html`) handles all of this interactively — the user uploads images, picks a theme, builds the slide structure, and exports a prompt. Alternatively, the user can provide assets directly in the conversation.

### Step 4: Generate the HTML slides

Read `references/skeleton.md` as the base template — it is a **complete, runnable HTML file** with a working 3-slide demo (Cover + Divider + Chart+Metrics). Pick the palette the user chose (from `references/palettes.md`), replace the `:root` block, and add content slides using the copy-paste blocks in `references/components.md`.

Use the layout budget from Step 1 to keep every slide within the visual density the chosen pattern can actually support. If the content exceeds the budget, switch to a better pattern instead of shrinking everything.

### Step 5: Visual review with the debugger

Open `assets/slide-debugger.html` in a browser and load the generated slides. The user can:
- **Inspect & adjust** — click elements to modify font size, weight, color, spacing, width, opacity
- **Inspect constraints** — view the nearest layout-constraining ancestors before assuming a width or max-width tweak will work
- **Edit text** — directly modify text content in the sidebar (with undo support)
- **Scan issues** — auto-detect overflow, clipped content, small fonts
- **Navigate slides** — check every slide with prev/next or arrow keys

When the user exports changes:
- Use **clean semantic export** by default for maintainable results
- Use **unsafe geometry export** only when the user explicitly wants to preserve fragile geometry or selector-based fixes

### Step 6: Iterate if needed

If the user wants significant content changes, go back to Step 1, 2, or 4. For minor tweaks, the debugger handles them directly.

Hard stop rule:
- If one slide requires **3 structural tweaks** in the debugger (for example repeated width, max-width, padding, or geometry corrections), do **not** keep patching. Go back to the pattern selection step and rebuild that slide.

## Quick start

1. **Open the configurator** — if the user wants an interactive way to set up their presentation, open `assets/slide-builder.html` in a browser. It provides visual palette selection (ColorHunt-style 4-color cards), logo/image upload, team member editing, slide structure building, and export. The user configures everything visually, then clicks "Generate Prompt for Claude" to get a ready-to-paste prompt.
2. **Read `references/skeleton.md`** — this is your HTML boilerplate. Copy it as the starting point for every new presentation. It contains the complete `<html>` structure, all base CSS, navigation JS, and placeholder slots for your content.
3. **Pick a palette** — read `references/palettes.md` and choose the palette the user selected. Each palette defines 4 colors (bg, surface, accent, accent-light) with full CSS variable mappings. Paste the `:root` block into the skeleton. If the user provides their own 4-color palette (e.g., from [ColorHunt](https://colorhunt.co/palettes/popular)), derive the CSS variables following the custom palette rules at the bottom of `palettes.md`.
4. **Build slides** — copy the full `<div class="slide">...</div>` blocks from `references/components.md`. Each pattern is complete with HTML structure, chart canvas IDs, and required JS init code. Follow the checklist at the bottom of that file when adding each slide.
5. **Test** — open in browser, check scaling (arrow keys), chart rendering, double-click fullscreen.

For academic or course presentations, prefer variants and recurring layouts over pitch-style CTA framing.

## Configurator (assets/slide-builder.html)

A standalone web app that the user can open in any browser. It provides:

- **Palette selector** — ColorHunt-style 4-color cards for all 12 palettes (6 dark + 6 light), click to pick. Each card shows the 4 colors side by side.
- **Logo upload** — drag & drop or click, converts to base64 for embedding
- **Image upload** — multiple images, also base64, for use in slides
- **Basic info** — title, subtitle, date
- **Team members** — add/remove, name + role
- **Slide builder** — add slides by pattern type, reorder (up/down), duplicate, delete, click to edit content
- **Slide editor** — for each slide: title, pattern, content notes, chart data, key metrics, and optional academic planning metadata
- **Export** — two options:
  1. **Export JSON** — full configuration as JSON (includes base64 images)
  2. **Generate Prompt for Claude** — produces a natural language prompt that references this skill and includes all the user's choices, ready to paste into Claude Code

When the user provides a prompt from the configurator, parse it and follow the instructions exactly. Read the referenced skill files (skeleton, theme, components) and generate the complete HTML file.

## Debugger (assets/slide-debugger.html)

After generating a slides.html, the user may find layout issues — text overflow, content clipped, fonts too small, etc. The debugger provides a visual DOM inspector to fix these without editing code manually.

Open `assets/slide-debugger.html` in a browser, then load the slides.html file. Features:

- **Inspect mode** — toggle on, then click any element in the preview to select it
- **Property editor** — adjust font-size (slider), font-weight, line-height, color (picker + hex), padding (4-direction), margin-bottom, width, max-width, opacity
- **Constraint chain** — inspect the nearest ancestors that constrain the selected element (`display`, grid/flex context, width, max-width, overflow, transform)
- **Text editing** — directly edit the text content of any selected element (debounced, with undo to restore original text)
- **Live preview** — all changes apply immediately in the embedded iframe
- **Scan Issues** — auto-detects: text overflow, content clipped by `overflow:hidden`, elements extending outside safe viewport, font sizes below 14px
- **Changes log** — tracks all modifications with one-click undo per change
- **Export CSS / HTML** — clean export by default, unsafe export only when geometry or fragile selectors are unavoidable
- **Slide navigation** — prev/next buttons and arrow keys to browse slides while inspecting

When the user exports CSS or HTML from the debugger, apply those changes to the original slides.html file.

## Architecture

```
scale-wrapper (viewport, theme bg)
  └─ presentation-stage (fixed 1920x1080, auto-scaled via transform)
       └─ slide (absolute positioned, display-gated visibility)
            └─ safe-viewport (5%-95% vertical, centers content)
                 └─ content-wrapper / unified-slide (actual content)
```

Key behaviors:
- **Auto-scaling**: JS calculates `min(viewportW/1920, viewportH/1080)` and applies `transform: scale(k)`. Responsive to resize and orientation change.
- **Slide transitions**: Prefer `display: none/block` or an equivalent non-ghosting approach instead of relying on opacity + visibility cross-fades.
- **Chart lazy-init**: Charts are created only when their slide first becomes active, using `window.__xxxInited` flags.
- **Keyboard nav**: Arrow keys (left/up = prev, right/down = next). Double-click for fullscreen.

## Color palettes

All palettes are curated from [ColorHunt](https://colorhunt.co/palettes/popular). Each palette defines 4 colors mapped to semantic roles: bg, surface, accent, accent-light. Read `references/palettes.md` for the full CSS variable set of each palette.

### Dark palettes (bg: dark)

| Palette | Colors | Vibe |
|---------|--------|------|
| Amber Gold | `#1C1917 #292524 #D97706 #FBBF24` | Warm, prestigious, finance-worthy |
| Deep Teal | `#0A1A1A #1A2E2E #0D9488 #5EEAD4` | Cool precision, analytical clarity |
| Crimson Night | `#1A0A10 #2D1525 #E11D48 #FDA4AF` | Bold energy, modern confidence |
| Forest Shadow | `#0A1A0E #152A1A #059669 #6EE7B7` | Growth, nature-inspired stability |
| Silver Elite | `#111214 #1F2228 #9CA3AF #F3F4F6` | Minimalist authority, lets content speak |
| Volcanic Orange | `#1A0805 #2D1208 #E6501B #FB923C` | Intense, attention-grabbing |

### Light palettes (bg: white/cream)

| Palette | Colors | Vibe |
|---------|--------|------|
| Paper Navy | `#F8FAFC #FFFFFF #1E40AF #3B82F6` | Classic academic, research |
| Cloud Teal | `#F1F5F9 #FFFFFF #0F766E #14B8A6` | Modern corporate, boardroom polish |
| Warm Terracotta | `#FEFCF7 #FFFFFF #C2410C #EA580C` | Warm professional, approachable |
| Lavender Mist | `#F2EAE0 #FFFFFF #9B8EC7 #BDA6CE` | Soft creative, dreamy |
| Sage Garden | `#F5F8F0 #FFFFFF #546B41 #99AD7A` | Natural, calm, earthy |
| Blush Coral | `#FFF5F0 #FFFFFF #E8637A #F9A8BB` | Warm, soft, approachable |

Light palettes require additional CSS overrides because the entire surface hierarchy inverts: cards become white with subtle shadows (instead of semi-transparent dark panels), text becomes dark, chart backgrounds turn white, and borders need more visibility. Each palette entry in `palettes.md` includes these overrides.

### Custom palettes

When the user provides their own 4-color palette (e.g., from ColorHunt), map colors to semantic roles:
- Dark palettes: darkest-to-lightest = bg, surface, accent, accent-light
- Light palettes: lightest-to-darkest = bg, surface, accent, accent-light

Then derive the full CSS variable set following the patterns in `palettes.md`.

## Slide patterns

Every slide should follow one of these patterns. Mixing them creates visual rhythm.

### Pattern 1: Cover slide
Full-bleed centered layout. Title with gradient or solid accent (100-112px, weight 900). Subtitle. Team grid. Date.

Academic variant:
- `cover-no-date` — for course decks, research presentations, or academic finals where date/team/logo blocks are optional and should be omitted rather than shrunk.

### Pattern 2: Part divider
Centered announcement card with accent-colored background. Part number + title + speaker name.

### Pattern 3: Chart + metrics (70/30)
Left 70% = chart area with title + canvas. Right 30% = 3 stacked key metric cards. Below: row of 4 secondary metrics.

### Pattern 4: Two-panel analysis
Equal or near-equal two-column layout. Each column is an independent card with chart + text. Good for comparisons.

Academic variant:
- `analysis-4-card-academic` — for repeatable policy / lesson / framework pages where a 2x2 or 4-card layout communicates recurring analysis better than generic two-panel storytelling.

### Pattern 5: Reason cards + sidebar
Left: 3 vertically stacked reason cards (numbered icon + title + body + highlight). Right: contrasting card (risk/summary).

### Pattern 6: Asymmetric grid
CSS Grid with `grid-template-areas` where one panel spans multiple rows. Good for slides with a large table alongside charts.

### Pattern 7: Three-column comparison
Three equal-width column cards. Each can have its own border accent color. For comparing strategies, risk levels, or time periods.

### Pattern 8: Timeline / Roadmap
Vertical alternating timeline with date nodes, or horizontal step flow. For project phases, milestones, strategic roadmaps.

### Pattern 9: Quote / Statement
A single powerful statement or quote, centered with oversized typography (120px) and decorative quotation marks. For key takeaways, vision statements, closing thoughts.

### Pattern 10: Process / Steps
Horizontal flow of numbered steps with gradient circle icons and arrow connectors. For methodology, workflow, process explanation.

### Pattern 11: Big Stat / Key Number
One dramatic number (180px) centered on screen with gradient fill, plus 2-3 supporting metric pills. For impact moments.

### Pattern 12: Image + Text (Split)
50/50 split: image fills one side, text content the other. For product showcases, case studies, visual explanations.

### Pattern 13: Before / After
Two contrasting panels. Left = problem (red-tinted border), right = solution (green-tinted). For pitching change.

### Pattern 14: Agenda
Numbered list of topics with speaker assignments in a 1- or 2-column grid. For the beginning of a presentation.

### Pattern 15: Icon Grid
Grid of items each with a gradient icon, title, and short description. For feature lists, service offerings, capability overviews.

### Pattern 16: Closing / CTA
Treat this as a family, not a single sales-style ending.

- `closing` — valid when the user truly wants thank-you, CTA, or contact information
- `closing-summary-wide` — academic default for recap, recurring takeaways, and final synthesis

Academic default:
- summary + recurring pattern + final takeaway
- no forced contact card
- no fake CTA if the deck is a course, class, or academic review

### Pattern 17: Comparison Table
Structured table comparing options across criteria with color-coded values. For feature comparison, scenario analysis.

### Pattern 18: Matrix / 2x2
Four-quadrant matrix with labeled axes. For BCG matrix, priority matrices, skill-will analysis.

For complete, copy-paste-ready HTML + JS code for each pattern, read `references/components.md`. It includes the full slide wrapper, chart init functions, and `showSlide()` wiring for every pattern.

## Key design rules

### Typography scale
| Element | Size | Weight | Color |
|---------|------|--------|-------|
| Cover title | 100-112px | 900 | Accent gradient or solid |
| Slide title | 54px | 900 | Accent |
| Panel title | 28-34px | 700-800 | Accent |
| Body text | 18-22px | 400-600 | var(--text-primary) |
| Metric value | 34px | 900 | Accent |
| Small detail | 14-18px | 400 | var(--text-muted) |

### Pattern fit and content budgets

Use these as planning defaults before generating HTML:

| Pattern | Title budget | Body budget | Structural budget |
|---------|--------------|-------------|-------------------|
| Cover / cover-no-date | <= 10 words | subtitle <= 18 words | team/date/logo blocks are optional, not mandatory |
| Chart + Metrics | <= 8 words | narrative <= 35 words | 3 primary metrics + 4 secondary max |
| Two-panel / analysis-4-card-academic | <= 8 words | each panel/card <= 28 words | choose 2 panels or 4 academic cards, not both |
| Quote / Statement | <= 18 words | no supporting paragraph unless truly short | use for statements, not dense explanations |
| Closing / closing-summary-wide | quote/final takeaway <= 16 words | recap block <= 3 repeated takeaways | avoid contact/CTA blocks unless explicitly requested |

If a slide exceeds its budget, refit the pattern instead of shrinking typography into submission.

### Spacing system
- Slide title to content: **40px**
- Between major sections: **24-30px**
- Between cards in a grid: **16-28px** (gap)
- Card padding: **18-24px**
- Chart container padding: **10-16px**

### Chart.js patterns
- **Lazy init**: Create charts only when their slide first becomes active. Use `window.__xxxInited` flag.
- **Responsive**: Always set `responsive: true, maintainAspectRatio: false`.
- **Theme-aware colors**: Use the accent and palette from the chosen theme file.
- **Dark vs light**: Dark themes use `rgba(255,255,255,.06)` for grid lines; light themes use `rgba(0,0,0,.06)`. Legend text matches `--text-primary`.

### Light theme specifics
When using a light theme, these changes apply on top of the base CSS:
- `body` and `.scale-wrapper` background → light color (`#F8FAFC`, `#F1F5F9`, or `#FEFCF7`)
- Cards → white/near-white with subtle `box-shadow` instead of semi-transparent dark
- Chart inner containers → light background
- Text → dark (`#1E293B` or similar)
- Indicator dots → `rgba(0,0,0,.15)` instead of `rgba(255,255,255,.3)`
- Cover title: consider solid accent color instead of gradient (cleaner on light bg)

## What to avoid

- **No external dependencies** beyond Chart.js CDN and Google Fonts.
- **No tech blue-purple (#6559F9, #8B5CF6, etc.)** as primary accent unless explicitly requested.
- **No scrollbars** — content must fit within safe viewport. Split if too much.
- **No absolute pixel positioning for text** — use flexbox and grid.
- **No autoplay** — presenter controls pace.
- **No emoji** — in the generated slides text, titles, labels, metric cards, or any content area. Use plain text only. Emoji in presentations looks unprofessional and renders inconsistently across devices.

## Dynamic layout adjustment

When generating slides, the layout must adapt to the actual content volume, not force content into a fixed grid. Key rules:

1. **Column count follows content** — if a three-column comparison has 4 items, use 4 columns (or a 2x2 grid). Never squeeze 4 items into 3 columns with overflow.
2. **Card count follows reasons** — the "Reason cards + sidebar" pattern supports 2-5 reason cards. Adjust the sidebar width accordingly. If there are 5 reasons, use a narrower sidebar.
3. **Metrics rows are flexible** — the row below the chart in "Chart + metrics" can hold 2-6 metric cards. Use `grid-template-columns: repeat(N, 1fr)` where N is the actual count.
4. **Team grid adapts** — the cover slide team grid uses `repeat(N, 1fr)` where N matches the member count (2-6 members).
5. **Split overfull slides** — if content genuinely doesn't fit (too many points, large tables), split into two slides with "continued" labeling rather than shrinking text below 14px.
6. **Font size floor** — never go below 14px for any readable text. If content exceeds space at 14px minimum, split the slide.

When in doubt, favor readability over density. A clean slide with fewer points beats a cramped slide with everything.

## When the user provides their own style reference

Extract the color palette and create an ad-hoc theme following the reference structure. Ensure contrast ratios are sufficient: on dark backgrounds, accents need to be bright enough for readability at presentation distance; on light backgrounds, text and accents need to be dark enough.