Reference SPA · v1.3.1
One deck. Four incompatible jobs.
Live delivery, independent reading, interactive inspection, and durable distribution require different attention models.
A live slide may rely on narration and controlled pacing. A distributed artifact must remain complete without the presenter. An exploratory view must expose detail without flooding the primary narrative. A printable artifact must survive without motion or interaction.
The system therefore starts from semantic content and produces context-specific renderings.
Failure pattern
Scaling one canvas creates predictable failures.
The same geometry cannot preserve pace, legibility, context, and interactivity at once.
Dense reference content competes with narration.
Labels shrink while targets and diagrams become unusable.
Speaker-dependent slides lose their reasoning and caveats.
Motion, progressive disclosure, and controls disappear.
The failure is architectural rather than cosmetic. Smaller fonts and tighter spacing cannot solve missing narration, lost interaction, or incompatible reading distances. Each context needs a renderer with its own density and composition policy.
Architecture decision
Make meaning canonical—not the stage.
The stage becomes one renderer. It no longer owns the knowledge.
The canonical model stores the assertion, evidence, narrative intent, reader detail, notes, sources, and rendering hints. Present, Read, Explore, and Print views then compose those elements for their specific cognitive and physical constraints.
Cognitive contract
One slide performs one cognitive job.
State the conclusion. Show the evidence. Add only the interpretation required to connect them.
What should the audience understand?
What makes the assertion credible?
Why does it matter now?
The assertion is the slide title. Evidence should be visually dominant enough to inspect. Interpretation should be concise. Definitions, caveats, methodology, and complete references remain available in Read or Explore mode.
Density
Stage evidence instead of shrinking it.
Density is the number of mental operations required—not merely the number of words.
Six encodings. Three comparisons. No clear entry point.
Use an attention budget. An assertion costs one unit. A primary chart or system diagram costs roughly two. A legend, independent annotation cluster, or interactive control costs another. When the stage exceeds the budget, move detail into another reveal, slide, or renderer.
Adaptive proof
Preserve meaning. Recompose the geometry.
The same semantic system becomes four deliberately different compositions.
Responsive behavior preserves semantic order and relationships rather than pixel positions. Compact landscape suppresses secondary copy and stages evidence horizontally. Portrait stacks evidence. Read mode reflows the same content into a complete article. Explore mode adds navigation and inspection rather than shrinking the stage.
Expanded layout grammar · 12 structural patterns
Use a small grammar. Vary the distribution.
Two-up, three-up, six-up, rails, bands, timelines, and system maps cover most recurring composition jobs.
This expands the structural grammar to twelve reusable distributions. The count is intentionally bounded: layouts are chosen by relationship, not decoration. A 2-up supports comparison or assertion/evidence. A 3-up supports sequence or balanced alternatives. A 6-up supports scan-oriented collections only when each item remains simple.
Additional relationship patterns—timeline, hub-and-spoke, decision tree, map-plus-detail, small multiples, and layered architecture—are available in Explore mode as semantic variants of these primitives.
Technical layout grammar · 12 evidence patterns
Pair code with its consequence.
Technical slides become legible when source, behavior, change, and result occupy explicit roles.
The technical grammar adds twelve evidence-specific patterns. Code should rarely occupy the entire stage without context. Pair it with annotation, output, diff state, contract response, trace evidence, architecture position, or test result.
Each technical specimen should identify the file or command, language, relevant version, and the exact lines under discussion. Long listings belong in Read mode or a linked source artifact.
Code formatting proof
Highlight the decision path—not every token.
Keep context visible, emphasize the lines being discussed, and place interpretation outside the code.
function compose(slide: Slide, mode: Mode) {const layout = selectLayout(slide.intent, mode);const evidence = rank(slide.evidence, mode);return layout.render({title: slide.assertion,evidence,detail: revealDetail(mode, slide.detail)});}
The full function remains visible so highlighted lines retain structural meaning.
Background and leading rule identify the lines currently being explained.
Explanations stay in a rail instead of interrupting syntax and indentation.
present → paced evidence
read → complete detailUse restrained syntax color. Reserve the strongest contrast for the active line or semantic decision. Keep indentation intact. Avoid screenshots when selectable, accessible HTML code can be used. Prefer approximately 45–75 visible characters per line in Present mode.
Line numbers are useful only when narration or documentation references them. For diffs, use redundant additions and deletions through signs, labels, and background treatment—not red and green alone.
Visual profiles
Profiles change the system—not just the hue.
Type, surface, contrast, density, borders, and atmosphere work together.
Longer measure. Restrained surfaces.
Each profile has independent light and dark color contracts. Technical clarity favors crisp structure. Calm utility softens secondary surfaces and motion. Editorial restraint changes display type and measure. Premium depth uses controlled dark surfaces and aura. Accessibility first removes atmosphere and strengthens redundant boundaries.
Platform architecture
One canonical model drives four renderers.
The content model is independent from any framework. Renderers may share semantic HTML and CSS primitives, but each controls its own visibility, composition, density, navigation, and output behavior.
Semantic contract
Separate the platform into four contracts.
Claims, evidence, sources, confidence
Intent, sequence, reveal stages, decision arc
Layout type, profile, responsive composition
Routes, metadata, offline assets, PDF policy
This separation prevents geometry from becoming the data model. It also enables linting, schema validation, source traceability, renderer replacement, and future export adapters without rewriting the underlying content.
Framework decision
Own the semantic shell.
Borrow presentation conventions without inheriting stage-centric assumptions.
- Multi-mode by design
- Adaptive mobile composition
- Native semantic baseline
The decision is not to reject existing frameworks. It is to avoid making their stage geometry the canonical knowledge format. Adapters can still target them when their strengths match a distribution need.
Quality gates
Validate every delivery context.
Structure alone cannot detect clipped evidence, broken themes, or unusable compact layouts.
Also test 2 themes × 5 profiles, target size, contrast, overflow, title lines, focus, history, and reduced effects.
The shield control runs in-browser structural and current-viewport checks. Release validation additionally runs an automated viewport and appearance matrix, including document overflow, active-stage overflow, target sizing, contrast tokens, and console errors.
Decision and action
Approve the schema and compiler boundary.
Keep this shell as the renderer and validator. Move authoring into a typed semantic model.
Typed slide schema and narrative intents
Semantic HTML and renderer-specific views
Content linting and visual regression
The reference shell now demonstrates the target architecture and validates its main delivery contexts. The next engineering phase is a content compiler that accepts structured source material, emits these semantic sections, and runs the same quality gates before distribution.