Vibe Slides

Create audience-ready browser presentations and prove that they communicate.

Completion bar

A deck is complete only when all of these are true:

• required source content is present and factually unchanged unless editing was authorized;
• each slide has one clear focal point and a deliberate role in the argument;
• important text, screenshots, charts, and UI evidence are readable without zooming at the target viewport;
• full-size and contact-sheet review show intentional density, whitespace, hierarchy, and variation;
• browser interaction and, when requested, rendered PDF pages pass their separate checks.

Static validation, successful rendering, correct page count, and absence of overflow are necessary but never sufficient evidence of visual quality. Do not deliver while any required completion condition is unproven.

Establish the contract

Infer topic, audience, purpose, delivery setting, language, approximate length, and density from supplied material. Ask only when a missing answer would change the story or acceptance. Distinguish:

• speaker-led: fewer words and larger type, without assuming animated reveals;
• reading-first: more self-contained evidence, still without scrolling.

After browser/HTML output is established, default to one HTML file that loads Reveal.js from a pinned CDN version. Network access is allowed. Do not replace Reveal.js with a custom runtime merely to avoid a dependency. Use another runtime only when the user requests it or Reveal.js cannot express the interaction.

Route the work before editing:

• new deck or substantial rewrite: read story.md, design.md,

reveal-contract.md, and visual-qa.md;

• faithful migration: also create the source inventory and page-aligned text

comparison described below;

• existing-deck repair: preserve the established visual language and read only

the references governing the affected behavior;

• PDF output: additionally read pdf-export.md.

Build the story before the page

Read [references/story.md](references/story.md) when creating or substantially rewriting a deck. Define the audience change, narrative spine, and one communication job per slide before implementation. Use audience-facing action titles; keep production notes out of visible slides.

When the user supplies a reference deck or webpage, classify the task before editing:

• faithful migration: preserve the source's complete content and visual

system while changing the presentation runtime;

• redesign: change narrative or visual language with explicit permission.

Default to faithful migration when the user asks to copy, reproduce, convert, port, or make a web/PDF version. Before implementation, capture every source page at the target viewport and inventory every visible heading, paragraph, number, table cell, image, diagram, footnote, and brand element. Do not treat summarization, rewording, page splitting, page merging, color substitution, or layout replacement as preservation. If pagination must change to prevent overflow, retain the source's information grouping and explain the change.

For HTML-to-HTML migration, extract visible text per source page and output slide, normalize whitespace, and run a page-aligned text diff before visual QA. Resolve every missing or changed line, including short labels, captions, units, dates, meaningful arrows, and status text. Side-by-side images do not replace this text diff.

Rebuild source text, tables, diagrams, and layout as native HTML/CSS. Use image-preserving playback only when the user explicitly requests it; detailed image and screenshot rules live in design.md.

Choose the visual system

Read [references/design.md](references/design.md) before creating or redesigning a deck. Derive the visual direction from the topic, brand, references, and delivery setting. When preference is unclear and visual choice materially changes the result, create 2–3 authentic title-slide previews for selection. Do not show internal labels such as “Option A” inside the slides.

For a new deck or authorized redesign without a source visual system, use the routing index in [references/design-systems/index.md](references/design-systems/index.md). Shortlist at most three relevant systems and load only the selected recipe after preview or explicit choice. Never apply a curated system to a faithful migration or established brand merely because it is available.

Before styling, write a compact slide plan containing the communication job, action title, complete content, primary visual, and layout silhouette for every slide. If planned content cannot remain readable, split the slide before implementation. Do not solve density by making screenshots or body text tiny.

Prefer a small layout vocabulary with varied silhouettes. Split content before shrinking text. Follow the motion defaults and exceptions in reveal-contract.md.

Implement with Reveal.js

For a new deck, run:

python3 <skill-dir>/scripts/scaffold.py <output.html> --title "Deck title" --lang en

Then replace the sample sections while preserving the runtime and accessibility contract. Read [references/reveal-contract.md](references/reveal-contract.md) before implementation or when changing navigation, fragments, notes, printing, or URL behavior.

Keep source provenance near the claim or visual. Use a visible footer, an <aside class="notes">, or a final sources slide. Default to notes for technical provenance; put sources on the canvas only when the audience needs them to interpret or trust that specific slide. Never expose a raw URL, draft-style Source: label, or internal citation placeholder as decorative footer copy.

When editing an existing deck, preserve its established visual language unless the user requests a redesign. Keep local assets on stable relative paths.

Validate and iterate

Run the deterministic contract validator:

python3 <skill-dir>/scripts/validate_deck.py <deck.html>

Fix every error. Treat warnings as review prompts, not automatic failures. Then read [references/visual-qa.md](references/visual-qa.md) and use an available browser tool to complete every required interaction, full-size, contact-sheet, viewport, overlap, fit, and communication gate defined there. Fix failures and repeat the affected checks.

Preserve semantic role as well as literal presence. A date, launch state, qualification, section label, or future commitment does not count as preserved when it is moved to a low-prominence footnote, generalized, or rewritten as a different roadmap state. For every source claim, compare value, tense/timing, scope, visual emphasis, and association with its heading, row, column, image, or diagram before marking content fidelity as Passed.

Record the required gates using the ledger in visual-qa.md. A failed or unrun required gate blocks delivery; do not downgrade it to a caveat.

Export a faithful PDF

Read [references/pdf-export.md](references/pdf-export.md) whenever PDF output is requested. Export from the final HTML with Reveal.js print mode; never rebuild the deck in a separate PDF layout system. Use:

node <skill-dir>/scripts/export_pdf.mjs <deck.html> <deck.pdf>

Follow every post-export comparison and repair gate in pdf-export.md. Do not call an export WYSIWYG based only on page count or successful file creation.

Treat demos and live tests as audience-facing quality samples, not diagnostic checklists. A deck that proves navigation but lacks a coherent story, visual thesis, layout variation, and presentation-ready copy has not passed visual QA.

Keep live-test and customer material outside the distributable Skill. Before promoting a prototype recipe, example, script fixture, or asset into skills/, remove customer names, brands, logos, slogans, people, proprietary product names, screenshots, and other identifying content. Re-run the repository distribution validator; a clean visual design abstraction is allowed, but a customer-derived example or asset is not.

Continue while a concrete in-scope correction remains. Stop and report the exact missing evidence when a required source, tool, access path, or user choice prevents further verification; never convert an unrun gate into a pass.

Deliver

Return the final HTML path, slide count, visual direction, dependency mode, and validation performed. When PDF was requested, return its path and describe the render-and-compare evidence. Mention any network dependency and any unverified behavior. Do not deliver scratch previews or test artifacts unless requested.