Webdeck

WebDeck

Create self-contained, animation-rich HTML presentations that run entirely in the browser without a build step.

Core Principles

1. Zero-build Output — Generated decks are single HTML files with inline CSS/JS. Optional PPT conversion, PDF export, and deployment may use separate 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. Progressive Disclosure — Read lightweight style indexes first. For bold templates, use small preview cards for style previews and load the full design.md only after the user picks that template.
5. Fixed 16:9 Stage (NON-NEGOTIABLE) — Every deck uses a 1920×1080 slide canvas scaled as a whole to the viewport. Slides must stay 16:9 on every screen, including phones. Do not reflow slide content to fit the device.

Design Direction

Make the deck feel authored for its subject and audience. Commit to a recognizable visual thesis: distinctive typography, a controlled palette, a consistent layout grammar, and one purposeful atmospheric or graphic device. Prefer a few well-orchestrated transitions over scattered effects.

Avoid generic defaults such as system fonts, purple gradients on white, interchangeable card grids, and decoration unrelated to the content. Use CSS variables to keep typography, color, spacing, and motion consistent across slides.

Fixed Stage Rules

These invariants apply to EVERY slide in EVERY presentation:

• Every deck has a viewport wrapper that fills the browser window.
• Every slide is authored inside a fixed 1920×1080 stage.
• The stage scales uniformly to fit the viewport. It may letterbox/pillarbox; it must not re-layout content.
• Do not use responsive breakpoints to rearrange slide content for phones.
• Use fixed internal slide measurements at the 1920×1080 design size.
• Slide visibility must be controlled by .active / .visible using visibility, opacity, and pointer-events from viewport-base.css. Do not use display: none / display: block for slide switching; later layout classes such as .slide-content { display: flex; } can override them and make every slide visible at once.
• Use clamp() only for non-slide UI outside the stage, or for small fallback previews where a full stage is impractical.
• 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 Modes

Ask the user whether this is primarily a reading deck or a speaking deck, then design around that answer:

Baseline limits still apply: no scrolling, no overflow, no overlapping panels, and no text below comfortable reading size. If content exceeds the selected density mode, split it into more slides instead of shrinking until it becomes cramped.

---

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, fixed-stage fitting is the biggest risk:

1. Before adding content: Count existing elements, check against density limits
2. Adding images: Fit them inside the 1920×1080 slide canvas. 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: the slide stage remains 16:9, no text overflows its card, no panels overlap, and screenshots look correct at 1280×720 plus one phone viewport
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 a new slide or reduce other content first. Never add images without checking if existing content already fills the 1920×1080 slide stage.

---

Phase 1: Content Discovery (New Presentations)

Use information the user already provided. Ask only for missing decisions that materially affect the deck, and group those questions into one concise message. If the environment provides a native structured-question UI, use it; otherwise use clearly numbered choices. If the brief is already sufficient, proceed without repeating questions.

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

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

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

Density (header: "Density"): How dense should the deck feel? Options:

• "Low density / speaker-led" — Big ideas, fewer words, more visual breathing room
• "High density / reading-first" — More self-contained detail for async reading

Do not ask about inline editing during Phase 1. Users should not have to choose editing behavior before seeing a draft. Inline editing is a post-draft affordance: include it by default unless the user explicitly asks for a locked/export-only file.

Remember the user's density choice. It affects slide count, typography scale, amount of text per slide, layout density, and whether to favor cinematic presenter slides or self-contained reading slides.

If user has content, ask them to share it.

Step 1.2: Image Evaluation (if images provided)

If the user provided no images and did not request image sourcing, skip to Phase 2.

If user provides an image folder:

1. Scan — List all image files (.png, .jpg, .svg, .webp, etc.)
2. Inspect each image — Use the agent's available image-understanding capability. If image reading is unavailable, use filenames/metadata and ask the user to clarify only when needed
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 the outline using the same structured-question mechanism when available: "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: Generate 3 Style Previews Directly

Based on purpose, audience, mood, and content density, generate 3 distinct single-slide HTML previews showing typography, colors, animation, and overall aesthetic.

Do not ask the user whether they want options or a preset picker. The default discovery experience is always visual comparison.

If the user already gave a vibe, use it. If they did not, infer the likely mood from the occasion, audience, content, and stakes. Keep the options diverse enough that the user can react visually instead of needing to articulate taste up front.

If the user explicitly names a preset or bold template, honor that as one option and generate the remaining preview slots around it.

Read STYLE_PRESETS.md for safe preset candidates. If bold-template-pack/selection-index.json exists, read that compact index too, but do not read any design.md files yet.

Preview mix rules:

• Generate 3 previews by default: 1 safe preset from STYLE_PRESETS.md, at least 1 bold template from bold-template-pack/selection-index.json, and 1 wildcard.
• The wildcard may be either a second bold template or a self-generated custom design. Choose whichever creates the strongest, most useful contrast for the user's occasion, audience, mood, and content.
• Do not force every expressive option to come from the template library. If the brief has a sharper, more specific design opportunity than the available templates, use the wildcard slot to design freely.
• For conservative or high-stakes decks, make the safe preset especially restrained; choose a calm, higher-formality bold template; make the wildcard either another restrained template or a custom design that feels authoritative rather than decorative.
• For expressive decks, keep the safe preset as a readable fallback; choose one strong bold template; make the wildcard adventurous, context-specific, and clearly different from both other previews.
• If bold template matches feel weak, use the wildcard as a custom design or fall back to another safe preset instead of forcing a template.

Custom wildcard design rules:

• Follow the Design Aesthetics section above: no generic "AI slop", no default font/color/layout choices, no purple-gradient-on-white clichés, no cookie-cutter dashboard/card look.
• Match the user's stated occasion, audience, mood/vibe, and content density. The custom design should feel authored for this deck, not merely "stylish."
• Make a deliberate visual thesis: distinctive typography, a committed palette, a recognizable layout system, and one strong atmospheric or graphic device.
• Keep it feasible for a full deck. The preview must imply a design system that can expand into section, content, quote, comparison, and closing slides.
• Use fixed 1920×1080 stage rules and pass the same preview authenticity checks as every other option.
• Never render "custom", "wildcard", "AI-generated", or design-process labels on the slide itself.

Bold template selection rules:

• Match user purpose and mood against mood, tone, best_for, avoid_for, formality, density, and scheme.
• Treat best_for examples as soft signals, not strict industry filters.
• Keep the three previews genuinely different from each other.
• After choosing bold template candidate(s), read only those candidate(s)' preview.md files from the preview_md paths in the selection index.
• Use preview.md only for title-slide previews. Do not read full design.md files until the user picks the final template.
• Do not read or copy template.html unless the selected final design.md is missing a critical implementation detail.

Preview authenticity rules (NON-NEGOTIABLE):

• Every style preview must look like a real first slide from the user's deck, not a diagnostic card.
• Never render internal workflow text on a slide: no preview, generated from, preview.md, template, preset, style option, Option A/B/C, file names, paths, or source-doc labels.
• Never render template names or slug names on the slide itself. Template/style names belong only in the message to the user.
• Never render user requirement notes as slide content, such as "sharp and provocative", "safe option", "bold option", "for internal sharing", or "audience: ...", unless the user explicitly wants that exact phrase to appear in the deck.
• If the slide needs chrome, use real deck chrome only: the deck title, section title, date, author, company, page number, or a genuine content phrase from the user's material.
• Before opening previews, inspect the visible text and revise if any internal metadata appears.

Save previews to .webdeck/slide-previews/ (style-a.html, style-b.html, style-c.html). Each should be self-contained and compact, showing one animated title slide.

Open each preview automatically for the user.

Step 2.1: 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.

Apply the user's density choice throughout the deck:

• Low density / speaker-led: Use more slides with fewer ideas per slide. Favor large headings, short phrases, visual metaphors, section beats, quote/statement slides, and presenter-friendly pacing.
• High density / reading-first: Make slides more self-contained. Use structured grids, comparison tables, annotated diagrams, captions, and concise explanatory copy. Keep hierarchy strong so it feels designed, not like a document pasted onto slides.

If the user's stated needs are mixed, choose the closer of the two modes instead of inventing a middle option: live audience persuasion defaults low-density; async circulation or detailed review defaults high-density.

Never let high density become visual clutter. If a high-density slide starts to overflow, split it or redesign it into a clearer structure.

If the user selected a bold template from bold-template-pack, read that one template's full design.md before generating. Do not read the other bold templates. Treat design.md as the design recipe:

• Preserve its fonts, palette, decorative vocabulary, spacing rhythm, and component grammar.
• Generate the final deck as a fixed 1920×1080 stage scaled uniformly to the viewport, regardless of whether the source template originally used deck-stage.js or viewport-fluid CSS.
• Treat viewport-fluid values in design.md as design proportions to translate into 1920×1080 stage coordinates. Do not keep them as live viewport reflow rules in the final deck.
• Keep the output as a single self-contained WebDeck HTML file.
• Do not copy demo slide content or mimic the source template too literally.
• Use template.html only as a last-resort implementation reference for the selected template.
• After generating, verify both content overflow and panel overlap in rendered browser screenshots. scrollHeight checks alone are not enough because grid panels can visually cover each other.

If the user selected a self-generated custom wildcard, treat that preview's CSS and layout as the design recipe:

• Preserve its fonts, palette, decorative vocabulary, spacing rhythm, grid logic, and component grammar.
• Expand the same visual system across the full deck. Do not switch to a preset or bold template after the user has chosen the custom direction.
• Design any missing slide layouts from that system rather than importing patterns from another style.
• Keep the output fixed-stage, single-file, and visually verified like every other deck.

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

---