| name | reveal-js-architect |
| version | 1.0.2 |
| description | reveal.js 6.0.1 presentation architecture — section/fragment structure, HTML vs Markdown-mode authoring, theming, plugin config, Reveal.initialize() options, vanilla setup, React extension via @revealjs/react 0.2.1. Use when building, structuring, or reviewing a reveal.js deck. |
Reveal.js Architect
Targets reveal.js 6.0.1 (vanilla) with an extension for @revealjs/react 0.2.1. Produces actual reveal.js source (HTML/JS deck scaffold or Markdown-mode slides) — never a slide-spec document; for that, see demo-presentation-architect (unrelated output format, not a dependency). Full project skeletons in RECIPES.md; pinned versions in STACK.md.
1. Scope & output
- Output is real reveal.js source —
index.html + <section> markup, or Markdown-mode slides, plus any main.js config. Never a slide-spec .md document.
- Vanilla is the default target. Reach for the React extension (§9) only when the deck already lives inside a React app or needs component-driven slide content (data-fetched slides, shared design-system components).
- This skill does not write slide copy for the user. It structures decks; content (titles, bullets) comes from the user or from a spec produced by demo-presentation-architect.
2. Interview-first protocol
Never scaffold a deck without finishing the interview. Ask in order; wait for each answer:
- Topic + slide count/duration — what's the deck about, how long is the talk.
- Vanilla or React? — plain HTML/JS project, or embedded in an existing React app via
@revealjs/react.
- Authoring mode — HTML
<section> markup, or Markdown-mode (data-markdown)? See §4 for the trade-off.
- Theme — a built-in theme (§5), or a custom CSS override.
- Plugins needed — syntax highlighting, speaker notes, math, zoom, search (§6).
- Delivery — static HTML file opened directly, or a bundler-based project (npm + Vite)?
3. Deck structure conventions
- Horizontal
<section> = new topic; nested vertical <section> = a sub-point of the same topic. Don't nest vertical slides more than one level deep — audiences lose the "back" direction.
- One idea per slide, same discipline as demo-presentation-architect §3 — split rather than cram.
- Fragments (
class="fragment") reveal progressively within a slide — use for build-up bullets or step-by-step diagrams, not as a substitute for splitting a slide.
- Speaker notes go in
<aside class="notes"> inside each section — visible only in speaker view (S key), never on the audience-facing screen.
data-transition overrides per-slide when a specific slide needs a different transition than the deck default — use sparingly, inconsistent transitions read as sloppy.- Never set
position, overflow, or display directly on <section>. reveal.js owns those properties on slide elements to drive its stacking and transition system (e.g. position: absolute on non-present slides, toggling display via the .present class). Custom CSS that overrides them breaks navigation silently — slides go blank on advance with no console error. Style content inside the section (a wrapper <div>), never the section itself.
- Make content fit by default; treat
overflow-y: auto as a fallback, not a strategy. For a live talk, a presenter forced to scroll mid-slide is a UX failure. When a slide is too dense, first tighten typography/spacing or split the slide (§3 "one idea per slide") — reach for internal scroll only as a defensive catch for unexpectedly long content, not as the default answer to "it doesn't fit."
4. Content authoring mode
- HTML sections — full control over markup, required when a slide embeds custom components, tables with rowspan/colspan, or fine-grained fragment ordering.
- Markdown-mode (
data-markdown) — faster to author, easier to diff/review, preferred for text-heavy decks (bullets, code blocks, quotes). Separate slides within one block with ---, vertical slides with --.
- Don't mix modes within one deck unless one section genuinely needs HTML control the rest doesn't — pick a default per deck and stay consistent.
- External Markdown files (
data-markdown="slides.md") keep content in version control separate from the shell; prefer this for long text-heavy decks over inline <script type="text/template">.
5. Theming & assets
- Start from a built-in theme (
black, white, league, sky, night, serif, simple, solarized, moon, beige, blood, dracula) — never build from scratch unless brand requirements demand it.
- Custom overrides go in a separate stylesheet loaded after the theme, not by editing the theme file in place — keeps upgrades painless.
- Images and media live alongside the deck, referenced with relative paths; large video/audio should be lazy-loaded via
data-src and data-lazy-load conventions to keep initial load fast.
- Watch compounding
em on nested elements that each set their own font-size. If a dense region (a wide table, a sidebar) shrinks via font-size: 0.4em and a generic deck-wide rule sets a child element's font-size in em too (e.g. p { font-size: 0.55em }), the two multiply rather than add — 0.4 × 0.55 ≈ 0.22em, far smaller than either value alone suggests. When nesting a shrunk region inside deck-wide em typography, size the inner region in rem or a fixed unit, or explicitly reset the child's font-size to 1em.
6. Plugins
Standard plugin set, loaded and registered in Reveal.initialize({ plugins: [...] }):
RevealHighlight — syntax-highlighted code blocks; pair with <pre><code data-line-numbers> for line-focus during a talk.RevealNotes — enables the speaker-notes view (S key); always include if <aside class="notes"> is used anywhere.RevealMarkdown — required whenever any slide uses data-markdown.RevealMath (KaTeX flavor preferred over MathJax for load speed) — only when the deck has actual formulas.RevealZoom — Alt/Option-click zoom into any element; low cost, safe default to include.RevealSearch — only for long reference decks the audience will navigate themselves, not for live-talk decks.
Don't register a plugin the deck doesn't use — each one adds a script tag and init cost.
7. Config conventions
- Sane defaults to keep:
hash: true (deep-linkable slides), controls: true, progress: true, center: true unless the deck's layouts are top-aligned by design.
transition — slide is the safe default; reserve fade/zoom/convex for decks where the transition itself carries meaning (rare).width/height — leave at defaults (1280×720) unless the deck targets a specific screen ratio; reveal.js auto-scales via its viewDistance and CSS scaling, don't hardcode pixel layouts inside slides.<section> only ever gets width: 100% from reveal.js — never height. Slide height is intrinsic (fits content), so any inner wrapper using height: 100% resolves against nothing and collapses to content size — backgrounds don't cover the canvas, and flex: 1; overflow-y: auto panels have no real box to scroll within. If a slide's layout needs a fixed canvas height (full-bleed background, scrollable body panel), set it in px on the inner wrapper, matching Reveal.initialize({ height }) exactly (e.g. a --slide-height: 720px custom property) — never % and never on <section> itself.slideNumber — enable for reference/training decks the audience revisits; skip for live pitch decks where it's visual clutter.- If the theme's background isn't pure white, override
.reveal-viewport { background-color: ... } to match it. When the window's aspect ratio doesn't match the configured width/height, reveal.js letterboxes with .reveal-viewport's own background — white by default in reveal.css — not the theme's. On a non-white theme this shows as an ugly border around the logical canvas.
8. Vanilla setup
CDN link for a single-file deck, or an npm + Vite project for anything version-controlled and multi-file. Full project skeleton (folder tree, package.json, main.js with plugin registration) in RECIPES § Vanilla project skeleton.
9. React extension (@revealjs/react)
- Use when the deck lives inside an existing React app, or slides need live component state (charts fed by app data, shared design-system components) rather than static markup.
<Reveal> wraps <Slide> children — each <Slide> maps to a <section>; fragments become a <Fragment> component, not the class="fragment" attribute.- Reveal's imperative API (
Reveal.initialize, plugin registration) is wrapped by the library's own hooks/props — don't reach into the vanilla API directly except for edge cases the wrapper doesn't expose.
- Don't reach for this extension by default — see react-architect for general React conventions; this section only covers the reveal.js-specific integration surface. Full component skeleton in RECIPES § React project skeleton.
10. Anti-patterns & review checklist
- Wall-of-text slides (no fragment/split discipline) — same failure mode as demo-presentation-architect flags for spec decks.
- Mixing HTML and Markdown-mode within one deck without a reason.
- Registering plugins that aren't used anywhere in the deck.
- Speaker notes that duplicate on-slide text instead of adding presenter-only context.
- Hardcoded pixel layouts fighting reveal.js's auto-scaling instead of using its centering/sizing config.
- Custom CSS setting
position, overflow, or display on <section> — silently breaks the stacking/transition system (blank slides on advance, no console error).
- An inner wrapper using
height: 100% (or flex: 1 inside it) to fill the slide — <section> never has a set height, so this collapses to content size instead of the canvas. Use a fixed px height matching Reveal.initialize({ height }).
overflow-y: auto used as the primary fix for a slide that doesn't fit, instead of tightening typography/spacing or splitting the slide — forces the presenter to scroll mid-talk.- Nested
em font-sizing where a shrunk region (table, sidebar) and a deck-wide child rule both use em — the values multiply, producing unexpectedly tiny text.
- Non-white theme with no
.reveal-viewport background override — letterboxing shows the default white viewport background instead of the theme's.
- React extension reached for out of habit when a static vanilla deck would do.
Before handing off: every slide has a clear single idea, plugins list matches what's actually used, transitions are consistent unless a specific slide has a stated reason to diverge, and speaker notes (if any) are present only where they add value.
