101 lines
9.8 KiB
Markdown
101 lines
9.8 KiB
Markdown
---
|
|
name: presentation-html
|
|
description: Build offline HTML decks with deliberate motion.
|
|
version: 0.5.0
|
|
author: RootAtSkic, Hermes Agent
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
metadata:
|
|
hermes:
|
|
tags: [presentations, html, revealjs, animejs, offline, accessibility]
|
|
related_skills: []
|
|
---
|
|
|
|
# HTML Presentations
|
|
|
|
Build editable, offline-first browser presentations using Reveal.js for navigation and Anime.js for intentional diagram motion. This is a global production workflow, not a fixed narrative, slide count, brand, or channel policy. Canonical spelling is **presentation-html**; `presentation-htlm` is a user typo, not a second skill.
|
|
|
|
## When to Use
|
|
|
|
- Create, revise, review or deliver an HTML slide deck.
|
|
- Add accessible interactive diagrams or purposeful motion to a browser presentation.
|
|
- Convert source material into a portable single-file deck without rasterizing text.
|
|
- Do not use this as the PowerPoint production workflow or authority for channel-specific claims.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3 for the dependency-free offline builder.
|
|
- Node.js 20+ and npm for the Playwright verification suite; install browser once while online.
|
|
- Full skill directory, including `assets/vendor`, not just this Markdown file.
|
|
- Read [research](references/research.md), [example catalog](references/examples.md) and [QA contract](references/qa.md) before changing the starter.
|
|
- Optional design/review skills may supplement this workflow; channel instructions remain channel-owned.
|
|
|
|
## Read on demand: runnable Anime.js registries
|
|
|
|
Select examples by the relationship they explain, not just their visual effect:
|
|
|
|
- [Element registry](references/registry-animejs-elements.md): SVG connection drawing, motion-path travel and spatial stagger. Read when choosing a single technique.
|
|
- [Composition registry](references/registry-animejs-compositions.md): dependency flow and assemble/explode/reassemble. Read when explaining a multi-part mechanism.
|
|
|
|
Editable configurations, renderer and preview live in `assets/animejs/`. Build the reusable offline gallery package with `python3 scripts/build-gallery.py` through `terminal`, then open `dist/animejs-gallery-0.5.0/index.html`. `npm test` exercises every registered example. Keep the registry ID, source, parameter constraints and verification coverage aligned when adding an example; do not load all examples into context unnecessarily. Gallery controls are for inspecting recipes, not mandatory controls for client slides. Wire slide departure/teardown explicitly when reusing a recipe.
|
|
|
|
## Read on demand: choreography and deterministic motion
|
|
|
|
Before adapting animation recipes, read [choreography](references/choreography.md): motion briefs, named timeline beats, paused ownership, deterministic seeking, SVG drawing/motion paths and spatial stagger. The starter exposes seek/replay/settle for authoring and QA without adding presentation controls. [Catalog patterns](references/catalog-patterns.md) records the three inspected `animejs` skills, source pins, license limits and rejected v3 examples. Tests exercise our original v4 equivalents; upstream snippets are not automatically compatible.
|
|
|
|
## Read on demand: explanatory mechanisms
|
|
|
|
Before designing an exploded view, modular assembly, product-internals explanation or reversible inspect/reassemble interaction, read [explanatory mechanisms](references/explanatory-mechanisms.md). It separates inspected Anime.js/Awwwards visual references from unverified implementation claims, links the original runnable `assets/mechanism.html` example, and defines adaptation and QA checks. Use it when motion must explain how parts form a whole—not to decorate tables. Build with `python3 scripts/build-mechanism.py`; test with `node scripts/test-mechanism.mjs` in the copied package.
|
|
|
|
## How to Run
|
|
|
|
Copy this complete package into a new working directory. Never edit an installed skill to create a client deck. Use `terminal` with that directory as `workdir`:
|
|
|
|
```text
|
|
python3 scripts/build.py
|
|
npm ci --ignore-scripts
|
|
npx playwright install chromium
|
|
npm test
|
|
```
|
|
|
|
The builder works entirely offline using vendored assets. Dependency/browser installation requires network once; deck playback and build do not. If a compatible Chromium is already installed, set `CHROMIUM_EXECUTABLE` to its actual executable when invoking `npm test`. Do not silently download a new runtime during an offline test.
|
|
|
|
Open `dist/presentation-html-demo-0.3.0.html` directly. The six-slide demo is a teaching example, not a mandated length. Source: `assets/starter.html`, `assets/app.js`, `scripts/build.py`. Tests: `scripts/test.mjs`.
|
|
|
|
## Procedure
|
|
|
|
1. **Freeze the brief.** Record audience, decision, duration, latest approved artifact, content sources and exact requested changes. Resolve slide feedback by visible content rather than unreliable numbering. Completion: every change maps to source and an acceptance check.
|
|
2. **Outline the narrative.** Context → mechanism → evidence → decision is a useful structure, not a compulsory sequence. One concept per slide; remove repetition rather than shrink text. End on the audience's decision, not provenance. Completion: each slide adds a unique reason to continue.
|
|
3. **Choose the visual system.** Use native HTML text and editable SVG. Choose a fixed aspect ratio and scale with Reveal. Use semantic grids for prose, geometry for real relationships, and one restrained accent. Work Sans is bundled as an optional example—not a universal brand. Completion: palette, typography, spacing and diagram vocabulary are explicit.
|
|
4. **Pin the runtime.** This package uses Reveal.js **6.0.2** and Anime.js **4.5.0**. Inspect actual package metadata and licenses before upgrading. The UMD bundles work from `file://`; keep ESM/build-system concerns out of the offline artifact. Completion: exact versions, hashes and notices match embedded bytes.
|
|
5. **Design interactions honestly.** A pointer cursor means a real action. Use native buttons or SVG groups with button role, accessible name, focusability, `aria-pressed`, Enter and Space handling. Do not give static diagram labels fake affordances. Stop propagation so activation does not advance Reveal. Completion: every interactive node works with mouse and keyboard.
|
|
6. **Add bounded motion.** Start with `transition: 'none'`; animate only to clarify grouping, sequence or relationships. Use Anime v4 `animate(targets, options)`, `createTimeline`, `stagger`, `ease`. Never paste v3 `anime({targets:…})` or `easing` options into v4. Settle active animations on departure, revisit, reduced-motion change and print. Final content must remain fully visible. Completion: no infinite decoration, flash, hidden final state or duplicate animation ownership.
|
|
7. **Make presentation controls explicit.** Include visible fullscreen enter/exit plus F; handle promise rejection and `fullscreenchange`. Preserve arrows, overview and focus. Restore the slide via hash with guarded local storage fallback; storage may be denied. Hide controls in print. Completion: real enter/exit—not a mocked call—passes.
|
|
8. **Build a portable release.** Embed CSS, JS, fonts and legal notices; no analytics, CDN calls, remote images or runtime fetches. Preserve previous delivered versions. Completion: a named single HTML file opens in an offline browser and has a SHA-256 manifest.
|
|
9. **Test the exact deliverable.** Update count/title/node expectations for the actual deck. Test every slide and every node, normal and reduced motion, early navigation, re-entry, overview, font loading, console, network, bounds, fullscreen, hash reload and print. A six-node sample does not prove a 46-node production deck. Completion: report identifies exact file hash and actual tested counts.
|
|
10. **Inspect and fix.** Render every slide separately after motion settles. Personally inspect the exact screenshots; geometry tests do not catch low contrast, hierarchy or unwanted default theme colors. Fix findings, rebuild and rerun. Independent review supplements self-review when available; disclose when unavailable. Completion: all final slides inspected and material defects resolved.
|
|
11. **Publish and deliver.** Include source, licenses, research links, final file, manifest and real evidence. If publishing to Git, verify immutable remote ref and file bytes, not just push output. Completion: attached artifact hash equals tested artifact hash, and limitations are stated.
|
|
|
|
## Pitfalls
|
|
|
|
- Reveal's `.reveal-viewport` rule can override a lower-specificity `body` palette; override `body.reveal-viewport` explicitly. Assert computed colors and inspect screenshots.
|
|
- Reveal hash writes are asynchronous. Wait for the expected hash before testing reload.
|
|
- Current Anime v4 API differs from legacy demos; some old minified bundles carry a version banner different from their advertised download version. Inspect actual bytes.
|
|
- Do not let Reveal Auto-Animate and Anime animate the same properties on the same element.
|
|
- Print is a separate state. A hidden toolbar check is not proof of paginated PDF quality.
|
|
- A license on a library does not license every third-party showcase's images, logos or music.
|
|
- Offline means no requests; a cache-warmed CDN presentation is not offline.
|
|
- Keep project names, channel identifiers, chosen slide count and user-specific review delivery preferences out of global defaults.
|
|
|
|
## Verification
|
|
|
|
- [ ] Complete package copied; exact pins and vendor hashes verified.
|
|
- [ ] Content/claim sources and all third-party licenses recorded.
|
|
- [ ] Source, output version and manifest agree.
|
|
- [ ] Every slide and actual interactive node tested, including Enter/Space and real action.
|
|
- [ ] Offline browser reports zero network attempts and zero console/page errors.
|
|
- [ ] Normal/reduced motion, fullscreen, navigation, overview and reload pass.
|
|
- [ ] Font and bounds checks pass; every final screenshot personally reviewed.
|
|
- [ ] Print state and any required PDF export independently inspected.
|
|
- [ ] Immutable publication verified; caveats distinguish automated checks from human review.
|