| name | amvcp-slide-decks |
| description | Author magazine-quality slide decks as one self-contained interactive HTML from a JSON deck contract. Letterbox stage, 16 layouts, 5 moods, 4 transitions, dependency-free (no reveal.js, no GSAP). Use when the user asks for a presentation, slide deck, talk slides, pitch deck. Trigger with 'slide deck', 'presentation', 'pitch deck', 'turn this into slides', '/amvcp-generate-slides'. |
| license | MIT |
| compatibility | Browser (ResizeObserver, requestAnimationFrame). Python 3.12+ renderer ships amvcp-slide.js + amvcp-designmd.js beside the HTML. |
| metadata | {"author":"Emasoft"} |
Slide Decks
Parent umbrella: skills/amvcp-visual-communication/SKILL.md — load the umbrella first to route between the 13 category skills.
Overview
Loads on requests for a presentation, slide deck, pitch deck, or "turn this into slides". Renders a deck of fixed-aspect "stage" slides from a JSON deck contract — the consolidated top-of-stack composite that converged five third-party slide projects into one dependency-free renderer. Seven sub-systems, all themed off the DESIGN.md --vc-* tokens, all prefers-reduced-motion safe, all light + dark correct by construction.
- Stage & viewport fitting — fixed-pixel stage with
transform: scale(ratio) letterbox, or responsive 100dvh fallback for mobile. No nested scrollbars ever.
- Deck navigation — keyboard, touch swipe, dot click, fullscreen, position persisted to localStorage.
- JSON typed-block authoring contract — the agent emits a deck as JSON; the renderer turns it into themed HTML.
- Named layout / composition catalog — 16 deduplicated layouts (manifesto, content, two-column, comparison, quadrant, data-story, metrics, timeline, bento, stack, full-bleed, quote, code-focus, closing, statement, section-divider). Bento has 7 grid sub-templates.
- Theme / preset system — every preset is a DESIGN.md file the Phase-1 engine resolves. No re-implementation of token resolution.
- Entrance & transition animation — 5 moods (minimal, editorial, dramatic, playful, techy), 4 transitions (crossfade, slide-left, zoom, page-turn), all CSS-only.
- Authoring-quality rules — the assertion-evidence headline rule (≥5 words + verb-or-stat) and content-density guard (≤6 bullets, ≤40 body words). Soft warnings, never thrown.
Prerequisites
- The DESIGN.md engine (
amvcp-designmd.js) loaded before the slide module — supplies the --vc-* tokens.
amvcp-slide.js ships beside the output HTML.- Optional sibling renderers when the deck uses delegated blocks:
amvcp-code-highlight.js (code block), amvcp-diagram.js (diagram block), amvcp-chart.js (chart block). Absent module + delegated block → throws a clear error naming the missing module (fail-fast — never a broken placeholder).
- A
motion: group in the DESIGN.md is optional — every CSS rule carries a canonical --vc-* fallback, so a token-less DESIGN.md still themes the deck correctly.
Instructions
- Inventory the source content — never drop content to fit a slide budget. Add slides instead.
- Pick ONE preset id, state why; commit to it. Mixing presets reads as indecision.
- Choose
aspect (16:9 / 4:3 / 3:2; default 16:9), fit (letterbox / responsive; default letterbox), mood (minimal / editorial / dramatic / playful / techy; default minimal), transition (crossfade / slide-left / zoom / page-turn; default crossfade).
- For each slide, pick a
layout from the catalog by job, not by looks (the Folio discipline) and write its blocks.
- Write every
heading as a full declarative sentence (assertion-evidence — §10.1 of the spec). Headlines <5 words with no verb and no stat collect a data-vsd-headline-warn attribute and a console warning; the deck still renders.
- Respect density limits: ≤6 bullets, ≤40 body words per slide. Overflow collects
data-vsd-overflow (soft warning).
- Emit the deck JSON into
<script type="application/json" id="vsd-deck">…</script> (XSS-safe, escape-free). Optionally embed the preset DESIGN.md as <script type="text/markdown" id="vsd-preset">…</script>. The slide module's boot(doc) reads them on DOMContentLoaded (or set window.__vsdManualInit = true to drive injection + render manually from a fixture).
The deck JSON contract
{
"kind": "deck",
"title": "Q3 Engineering Readout",
"aspect": "16:9",
"fit": "letterbox",
"mood": "minimal",
"transition": "crossfade",
"loop": false,
"slides": [
{ "layout": "manifesto",
"blocks": [
{ "type": "eyebrow", "text": "Q3 2026" },
{ "type": "heading", "text": "Latency dropped 38% after the cache rewrite shipped." },
{ "type": "text", "text": "Every p99 path now clears 200ms." }]}
]
}
Output
Single self-contained HTML file: embedded deck JSON + optional embedded preset DESIGN.md + amvcp-designmd.js + amvcp-slide.js shipped beside, no CDN, no build step. Every .vsd-slide carries data-ve-id / data-ve-type="slide" / data-ve-label so the runtime's selection layer keeps slides click-selectable / commentable. Native browser "Save as PDF" produces one slide per page (the @media print block restores the natural stage size and unhides every slide).
Error Handling
- Unknown block
type / unknown layout / unknown mood/transition/aspect/fit → fail-fast throw with the offending JSON path (e.g. slides[3].blocks[1]: unknown block type "mermaidd").
- Delegated block + missing sibling module → throw naming the module (
window.amvcpCodeHighlight.renderInto is not available).
- Headline weak → soft warning (
console.warn + data-vsd-headline-warn); deck still renders. Stylistic judgement, not a structural error.
- Slide overflows density limits →
data-vsd-overflow attribute + a densityWarnings entry; no scrollbar is ever added.
- Reduced motion → every entrance + transition substitutes to opacity-only / instant; no
animation:none that leaves a block stuck at opacity 0.
- JS disabled → the embedded
<noscript> would expand the deck into a vertical stack of full-height slides (page expands, no inner scroll).
Examples
Input: "Turn the Q3 readout into a 6-slide deck. Use a dramatic entrance and crossfade between slides."
Output: A single HTML file with a 6-slide JSON deck embedded under id="vsd-deck" (mood: dramatic, transition: crossfade, aspect: 16:9, fit: letterbox). Six <section class="vsd-slide" data-ve-id="s1..s6" data-ve-type="slide"> carry layouts picked by job: manifesto for the opening anchor, metrics for the stats row, data-story for the chart, comparison for the then/now contrast, bullets inside content for the action items, closing for the wrap. Click any slide to open the comment modal (the runtime's selection layer reads the standard data-ve-* attributes unchanged).
Module API surface
window.amvcpSlideDeck (browser) and module.exports (Node, for the test harness):
injectSlideCSS(doc) — append the deck <style> to doc.head. Idempotent.parseDeck(jsonText|object) — validate a deck; returns the normalised deck object. Throws on any structural violation.renderDeck(deck, mountEl) — build the deck DOM into mountEl. Returns the built .vsd-viewport.createDeck(viewportEl) — wire navigation; returns a Deck (with go/next/prev/current/count).fitStage(viewportEl) — recompute the letterbox scale.validateHeadline(text) — assertion-evidence soft check; returns {ok, reason}.boot(doc) — full self-init from an embedded deck JSON.refresh(viewportEl) — re-fit after dynamic DOM changes.
Authoring discipline (the headline rule)
Bad: Q3 Results (label, no verb, 2 words). Good: Latency dropped 38% after the cache rewrite shipped. (claim, verb dropped, stat 38%). Every heading is a complete sentence the audience can disagree with — the single highest-leverage anti-slop rule the deck enforces.
When to choose this category (decision matrix)
| User says / wants | Pick amvcp-slide-decks if... | Otherwise route to... |
|---|
| "slides" / "deck" / "presentation" / "pitch deck" / "slide show" / "talk slides" | ALWAYS. Explicit ask. | — |
/amvcp-generate-slides slash command | Always. | — |
--slides flag on another slash command | Always (the flag opts in). | — |
| "Turn this into a deck" / "format for projection" / "make this presentable" | Always. | — |
| "Make a one-pager" / "make a shareable graphic" | YES → use kind: "poster" in this skill. | — |
Multi-slide artefact that is PACED (paged by → or by the presenter) | YES. | — |
| Scrollable article / report read at the reader's pace | NO — scrollable, not paced. | amvcp-prose-pages |
| Single chart driving a finding (no surrounding deck context) | NO — pick the chart skill directly. | amvcp-charts-and-dashboards |
| Single diagram standalone (no surrounding deck context) | NO. | amvcp-graph-diagrams |
| Comparison table of N options | NO — pick the table skill directly. | amvcp-choice-tables |
| "Make a comment thread on this artefact" | NO — that's the modal-comments layer, not the slide layer. | amvcp-modal-comments |
| "Print this for a handout" | YES if the source naturally paginates as slides (cover-letter / project plan). NO if it's an article. | amvcp-prose-pages for articles. |
See 41-decision-matrix-when-to-choose-slides for the full
What this is · Decision flowchart · When to pick slide-decks · When NOT to pick slide-decks · Boundary cases · Authoring-quality checklist before picking slide-decks · Lib functions called · When to use this reference · Common mis-dispatches · Don'ts · Visual verification · Source provenance
boundary-case discussion.
Modes
This skill supports data-ve-mode="readonly" only. Slides are presentation content — every slide block is selectable for comment, but the per-element 3-state decision pill (R20-R23 of amvcp-self-debug-rules) does NOT apply. For a "rate each slide" or "approve/deny each slide" flow, use amvcp-tables with each row referencing a slide.
Composability
Composes with every other amvcp-* skill on the same page (R22). Slides typically embed diagrams, charts, code blocks, math via their respective skills. The only exclusive skill is the overlay-runtime (R24).
Resources
The 41-reference progressive-discovery catalog for the slide-decks
skill — layouts, motion, blocks, authoring quality, theming,
integration, debugging — is housed in its own index file so this
SKILL.md stays under the progressive-disclosure word budget. Open
the index to navigate; each entry there carries its own embedded
TOC.
- resources-index — full 41-reference catalog
Foundation refs · Layout catalog refs · Motion refs · Block refs (per family) · Authoring-quality refs · Theming refs · Integration refs · Debugging refs · Routing ref · Legacy long-form catalog
Visual verification
Every authoring change to a deck — new slide, new layout choice,
new preset, new transition — MUST be verified via the dev-browser
screenshot path described in amvcp-self-debug-rules.
Capture light + dark at 1280×720; verify the deck reads at projection
distance; verify the console reports zero amvcp-slide: errors and
that any data-vsd-headline-warn / data-vsd-overflow warnings are
either fixed or acknowledged as intentional.
