Files
presentation-html/SKILL.md
T

88 lines
8.2 KiB
Markdown

---
name: presentation-html
description: Build offline HTML decks with deliberate motion.
version: 0.2.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: 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.1.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.