HTML Slide Deck Generator

Single-file HTML presentations: a scroll-snap engine with keyboard, tracks, speaker notes and deep links, the Bridge's DESIGN.md brand or one of 10 style presets, light and dark, fonts embedded, nothing fetched from a network. The foundation (tokens, fonts, the quality gate, the send bundle) is shared with html-canvas and called from there, never copied: this skill needs skills/html-canvas/ next to it.

Decision tree

Build path: generator first

Never hand-assemble a deck. The generator writes every generated part between markers, asserts each splice, and keeps the deck refreshable.

python3 skills/html-slides/scripts/new-deck.py --title "Quarterly review" --lang en \
    --slides slides.html --out work/tasks/<slug>/deliverables/deck.html

1. Plan the content against the density limits in reference/rules.md: title, sections, content slides, closing. Split, never cram.
2. Write the slides as one HTML fragment of <section class="slide ..."> elements, from the 11 slide types in reference/slide-types.md. Without --slides the deck gets one title slide to fill in.
3. Generate with new-deck.py. Engine options (tracks, counter format, back link) go on the deck element with --deck-attr data-NAME=VALUE. It splices the pre-paint theme script, the embedded fonts, the tokens, assets/slide-engine.css and assets/slide-engine.js (first line slide-engine v2), plus the stage module with --with-stage and each deck module named by --with (reference/modules.md). --lang de localises the controls, the help and the ARIA texts.
4. Run the gate (Definition of done), then open the file in the browser.

Updating an existing deck: new-deck.py --refresh deck.html rewrites only the marker regions the deck already carries (engine, tokens, fonts, preset CSS, stage, modules) from the current assets, DESIGN.md and preset. The slides are never touched, and a second run gives the same bytes. A deck from before the generator has no markers: leave it as it is (its engine is embedded and keeps working), or move its slides into a fresh new-deck.py --slides build. Details: reference/deck-build.md.

Look: DESIGN.md first, style presets as fallback

• DESIGN.md wins. When one is found walking up from the output path, or given with --design (a path or an id under identity/designs/), the design preset is the default. A deck inside the Bridge wears the design the Bridge resolves (the theme's branding.design, else the root DESIGN.md); a deck written into another repository keeps that repository's DESIGN.md: colours through presets/design.map.yaml and html-canvas/scripts/design-to-css.py, families and weights from DESIGN.md typography. Nothing is hand-picked. The preset also holds the brand rules a slide's markup cannot break: headings in the heading colour, status colours for state only (a chapter colour or glow from a snippet gives way), 1px lines, code in the mono family on the muted surface, no shadow or texture. .fx on <html>, the deck or a slide brings the decoration back.
• Style presets (--preset swiss-modern and the others) are for a deck that should not carry the house brand, and the fallback without DESIGN.md (the one marked default: true). Offer the picker assets/discovery-menu.html when the user wants to choose; no answer means the default.
• Theme contract: the engine keeps .theme-dark / .theme-light on <html>, stored as slide-theme, the OS preference while nothing is stored, key T toggles. The shared rule set is html-canvas/references/theme-contract.md.
• Fonts are embedded by default (style presets depend on their typefaces); --no-embed-fonts leaves the deck on its fallback stacks. A send copy always embeds.

Definition of done

verify-page.py from html-canvas is the gate. Exit 0 is done; a requested browser pass that cannot run is an error, not a pass.

V=skills/html-canvas/scripts/verify-page.py
python3 $V deck.html --design DESIGN.md   # always: no external or sibling file, no placeholder, no stray hex
uv run --with playwright python $V deck.html --design DESIGN.md --deck   # before delivery: renders it,
                                          # contrast per theme, overflow per slide, one print page per slide

Pass the same --design the deck was built with. Without it the gate takes the nearest DESIGN.md at or above the deck, but never above the project root (the first folder with .git or bridge-config.yaml), and says which one it used. A deck built from another DESIGN.md gets a design-source warning. --deck needs playwright and its chromium; a bare python3 without them fails as browser-skipped.

A style preset deck is off brand by definition: while a DESIGN.md is in reach, the gate reports its preset colours as hex errors. That is the one known exception; every other finding gets fixed.

Send path

An instance names its own wordlist in bridge-config.yaml under html_slides.anonymity_wordlist, never in this skill. Order and options: reference/output-formats.md.

Files

Tests

PYTHONDONTWRITEBYTECODE=1 uv run --with pytest --with pyyaml --with playwright \
    python -m pytest skills/html-slides/tests -q -rs

Browser tests need playwright and its chromium and skip without them; the render-pdf tests also need node playwright. Changing the engine, a preset or a count in these docs means running them; tests/test_docs.py holds the counts to the tree.