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), 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. 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.