Reference SPA · v1.0
HTML decks are a distinct medium.
Not a document cut into rectangles. Not a desktop canvas scaled onto a phone.
This deck is also the reference implementation. Change modes from the header. Presentation mode provides controlled pacing. Read mode produces a complete distributed artifact. Explore mode exposes slide-level detail and sources. Print mode uses dedicated landscape rules.
Core architecture
One semantic source should serve four attention contexts.
Live delivery, independent reading, interactive inspection, and durable distribution require different density models.
A live slide can rely on narration. A distributed slide cannot. The canonical content model therefore separates the assertion, evidence, reader detail, speaker notes, and sources instead of forcing all information into the visible stage.
Cognitive UX
A slide should perform one cognitive job.
State the conclusion. Show the evidence. Add only the interpretation needed to connect them.
Assertion
Say what the audience should understand.
Evidence
Show the visual, data, or system relationship.
Interpretation
Explain why the evidence changes the decision.
Assertion-led titles reduce the effort required to infer the slide’s purpose. Evidence should occupy the primary visual field. Supporting detail belongs in the distributed layer unless it is essential to understanding the live argument.
Narrative architecture
The deck should progress from orientation to action.
Orient
Establish context and the system boundary.
Create tension
Show why the current model is insufficient.
Resolve
Present evidence, choices, and the target state.
Activate
End with a decision, owner, and next move.
Section names such as “Architecture” and “Security” describe storage categories. They do not create an argument. A decision arc links each section to an audience question and preserves cognitive momentum.
Content density
Density is the number of mental operations required.
A diagram with eight labels can be denser than forty words of simple prose.
Density assessment should include concept count, object count, comparisons, visual encodings, interaction requirements, required prior knowledge, and the time available. The implementation does not auto-shrink text to conceal an overloaded slide.
Layout grammar
Use a bounded set of layouts, each with a declared purpose.
The layout type belongs in the content schema. This prevents generated decks from inventing one-off structures and makes responsive transformations predictable. Variation should come from content and visual profile rather than unbounded geometry.
Complex information
Reveal complexity while keeping the map stable.
The preferred sequence is overview → focus → synthesis. Nodes retain their positions between stages. Semantic zoom reveals additional information layers instead of merely enlarging pixels. Direct labels reduce legend lookup and eye travel.
Data storytelling
Lead with what changed, then expose the baseline.
The live view prioritizes the signal. Read and explore modes preserve the complete context.
For operational and executive data, the visible sequence should be: change, tolerance exception, consequence, and action. Complete tables, methodology, and alternate cuts remain available in the distributed layer.
Typography
Type roles should scale with the slide container.
The same slide may appear fullscreen, embedded, in overview, or beside an inspector.
Display
Assertion title
Evidence annotation uses a longer measure and calmer rhythm.
container-query: inline-size
The correction sequence for overflowing text is: remove redundancy, shorten the assertion, move detail to read mode, change the layout, split the cognitive job, then make only a small type adjustment. Automatic shrink-to-fit is intentionally excluded.
Mobile pacing
A phone needs a presentation control plane, not invisible swipe zones.
Navigation remains explicit, safe-area aware, and available through multiple input methods.
The implementation supports visible previous and next controls, keyboard navigation, browser history, overview navigation, direct links, and optional swipe. Swipe pauses when an interactive component owns the gesture. Control targets are designed around a 44–48 CSS-pixel operational target.
Responsive + adaptive
Do not shrink the desktop stage. Recompose the meaning.
Same geometry
Tiny labels, weak targets, brittle overflow, excessive empty margins, and pointer-first interactions.
Same meaning
Stacked evidence, selectable layers, portrait pacing, direct labels, and touch-first controls.
The implementation uses a 16:9 stage where it fits. Portrait and compact contexts switch to intrinsic-height compositions. Split, sequence, system, and comparison layouts become different structures rather than scaled replicas.
Aura effects
Ambient color should establish tone without carrying meaning.
Use aura for
Section atmosphere, depth, visual continuity, and rare cinematic emphasis.
Do not use aura for
Status, severity, selection, chart categories, or any meaning lost in forced-color mode.
The deck uses two pseudo-element radial gradients and one static tertiary field. Only transform and opacity animate. Aura intensity is adjustable from zero to four and is removed in forced-color and accessibility-first profiles.
Theme profiles
Name profiles by communication quality, not universal emotion.
Color and emotion have many-to-many relationships. Profiles therefore specify intended communication attributes while retaining semantic color roles, contrast requirements, and independent light and dark validation.
SPA architecture
A canonical content model drives four renderers.
- One active idea
- Fragments
- Presenter controls
- Complete narrative
- Sources
- Searchable flow
- Slide rail
- Inspector
- Interactive evidence
- Stable pages
- No animation dependency
- Opaque surfaces
The same semantic sections remain in the DOM. CSS controls composition. JavaScript coordinates the active slide, fragments, history, notes, wake lock, fullscreen, and validation. This keeps the baseline meaningful before enhancement.
Semantic contract
Content, narrative, presentation, and distribution remain separable.
Each slide in this file declares an ID, title, section, and intent. Visible evidence, reader detail, speaker notes, and sources are distinct semantic regions. This allows future generation, linting, export, and alternate rendering without scraping presentation geometry.
Framework decision
Use a small custom shell. Borrow conventions, not framework assumptions.
| Approach | Strength | Constraint | Fit |
|---|---|---|---|
| Custom semantic shell | Multi-mode, adaptive, native-first | Own the controller | Primary |
| Reveal.js | Mature speaker controls | Stage-centric defaults | Conventional decks |
| Slidev | Developer components and export | Build and runtime weight | Code-heavy decks |
| Marp | Simple Markdown publishing | Limited adaptive interaction | Briefings |
The shell should remain small and interoperable. The content model can later support export adapters for Reveal.js, Marp, PDF, notes, and accessible text without adopting their rendering constraints as the canonical format.
Quality gates
A generated deck is not finished until it passes structural and viewport checks.
Use the shield icon in the header to run the built-in validation harness.
The harness checks duplicate IDs, slide metadata, assertion headings, missing control names, target sizes, and stage overflow at a 1440 × 810 validation canvas. Runtime responsiveness still requires visual testing at compact portrait and landscape breakpoints.
Reference standard
The deck becomes a reusable publishing platform.
This file is a starting architecture. The next platform layer should separate slide content into a canonical JSON or Markdown model, preserve these semantic regions, and compile to the self-contained HTML shell.
Next move
Separate the canonical content model, then make this shell the renderer and validator.
The visual system is implemented. The next engineering boundary is authoring and compilation.
Recommended next phase: define the typed slide schema; create a compiler that generates semantic sections; add content linting and screenshot regression tests; then add optional export adapters. Keep the single-file artifact as the baseline distribution target.