gnommoplayer/slide-template-guidelines.md

Slide Template Guidelines

This note gives a short “when to use it” rule for each supported GlitchPlayer slide template.

The purpose is to help:

• human authors
• AI slide agents
• editor integrations

pick the simplest effective template for a given explanation beat.

General Rule

Slides should not repeat the script.

A slide should do one job:

• show a visual
• define a term
• highlight a contrast
• embed an interaction
• frame a quote
• focus attention on one equation

If a slide is trying to do more than one of those at once, it is probably the wrong template.

Supported Templates

SquareYellow

Use when:

• one image does most of the work
• you need a short strong header
• the talking head should stay visible beside or below the slide

Good for:

• mood
• framing
• one clear visual metaphor

Avoid when:

• the idea needs more than one sentence
• the viewer needs to compare two things
• the slide is mainly about numbers or interaction

FullscreenSplit

Use when:

• one image and one short text block should share attention
• you want a clean fullscreen transition
• you need to conceal a segment seam under the slide

Good for:

• contrast
• one visual plus one claim
• scene-setting slides

Avoid when:

• the text starts turning into a paragraph
• the image is decorative rather than explanatory

EquationFocus

Use when:

• one equation is the main thing the viewer should understand
• the script is defining a formula or symbolic relationship

Good for:

• definitions
• identities
• simple derivation checkpoints

Authoring rule:

• keep the header short
• keep the title short
• use one LaTeX expression only
• annotation should explain the equation in plain language

Avoid when:

• you need to compare two equations
• the expression is too large or multi-step

QuoteImage

Use when:

• a quote is the slide
• the image is there to support emotional or contextual framing

Good for:

• rhetorical emphasis
• historical voice
• strong claims

Avoid when:

• the quote is longer than the viewer can absorb quickly
• the image is carrying a second unrelated message

ChartSingle

Use when:

• one compact chart tells the story
• you are comparing a few values
• the script needs one clean quantitative contrast

Good for:

• 3 to 5 bars
• one pattern
• one takeaway

Authoring rule:

• use a short header
• keep the title direct
• body is optional and should be brief
• label names should be short

Avoid when:

• the viewer needs to inspect lots of data
• the chart needs axes, legends, or technical notation to make sense

ProcessFlow

Use when:

• the script is describing a pipeline or mechanism
• the viewer needs sequence, not comparison

Good for:

• 3 to 5 steps
• causal flow
• product/process explanations

Avoid when:

• the steps are too wordy
• the process is branching or deeply conditional

DefinitionCard

Use when:

• the job of the slide is to define one concept
• the audience needs a crisp shared term before moving on

Good for:

• vocabulary
• named concepts
• framing a new abstraction

Authoring rule:

• header is context
• term is the anchor
• definition is plain language
• example is concrete

Avoid when:

• the concept needs a diagram more than text

GlitchComponentFrame

Use when:

• the explanation becomes clearer if the viewer can manipulate the model directly
• the slide should host a real interactive Glitch component
• the script benefits from 3D, simulation, or hands-on exploration

Good for:

• 3D scenes
• parameterized simulations
• interactive paradoxes
• exploratory visual models

This template is intended for hosted Glitch components, not static images.

Current contract:

• header
• componentId
• componentUrl
• caption

Current runtime model:

• the slide embeds the component in an iframe
• the component is expected to be hosted independently
• if componentUrl is omitted, the player resolves a default path from:
  • VITE_GLITCH_COMPONENT_BASE_URL
  • the convention glitch_${componentId.replace(/-/g, "_")}
  • and targets that component's index.html
• the player treats it as an interactive surface

Guidelines:

• use this only when interaction adds real explanatory value
• prefer a stable hosted URL or a stable public/glitch/... deployment path
• keep the header short
• caption should explain what the viewer should try or notice
• assume the component itself provides the deeper interaction

Avoid when:

• a static image would do the job
• the component is still too unstable to embed
• the interaction is not tied to the narrated idea

Choosing Between Static And Interactive

Default to a static template first.

Use GlitchComponentFrame only if at least one of these is true:

• the viewer learns by manipulating parameters
• the shape, motion, or geometry matters
• the explanation is weaker as a static image
• the component can stand on its own as a small exploratory object

If not, use:

• SquareYellow
• FullscreenSplit
• ChartSingle
• EquationFocus
• DefinitionCard

Those will usually produce a cleaner lecture.