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.