/slide-authoring

name: slide-authoring
description: Technical reference for writing or editing open-slide pages — file contract, 1920×1080 canvas, type scale, layout, palette/visual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides/<id>/`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like "edit slide", "tweak this page", "fix the layout", "change the palette", "reveal one by one", "add a transition", "morph transition", "write the speaker notes", "generate the script / talk track", "preview / screenshot a page", "check how it looks", "investigate the slide framework", "how do slides work here".

Authoring open-slide pages

This skill is the **technical reference** for everything that happens inside `slides/<id>/index.tsx`. It does not own a workflow:

• `create-slide` owns "draft a new deck" — it asks the user scoping questions, then delegates the *how* to this skill.
• `apply-comments` owns "process inspector markers" — it finds markers and applies edits, but the edits themselves follow the rules here.
• `current-slide` resolves deictic references ("this page", "the slide I'm on") to a concrete `slideId` + `pageIndex`. Consult it **first** when the user references the current slide without naming it, then come back here for how to edit it.
• Any ad-hoc slide edit (manual tweak, one-off fix) should also consult this skill before touching the file.

When any of those paths reach the point of *writing React code for a page*, this is the source of truth. Do not duplicate the knowledge below into other skills — link here instead.

Primitive references

Each framework primitive has a full reference file under `references/` in this skill — contract, worked examples, and its own anti-patterns. This file keeps only the always-on rules and a short summary per primitive. **Read the relevant reference file before using a primitive on a page**:

| Primitive | Read before | File | | --- | --- | --- | | `design` const + `var(--osd-X)` tokens | writing any new slide (default baseline) | `references/design-system.md` | | Assets + `<ImagePlaceholder>` | importing images/videos or leaving a placeholder | `references/assets.md` | | Webfonts | loading any non-system font | `references/webfonts.md` | | `useSlidePageNumber()` | rendering a page-number footer | `references/page-numbers.md` | | `<Steps>` / `<Step>` | staging a page's reveal | `references/steps.md` | | `SlideTransition` | declaring any enter/exit animation | `references/transitions.md` | | `MorphElement` + `morph` | morphing a shared element across pages | `references/morph.md` |

Hard rules

• Put the slide under `slides/<kebab-case-id>/`.
• Entry is `slides/<id>/index.tsx`. Images/videos/fonts go under `slides/<id>/assets/`.
• Do **not** touch `package.json`, `open-slide.config.ts`, or other slides.
• Do not add dependencies. Only `react`, `@open-slide/core`, and standard web APIs are available.
• A slide is **one `index.tsx` plus `assets/`** — nothing else. Do not create sibling `.tsx`/`.ts` files (`Card.tsx`, `components/`, `helpers.ts`, etc.); helper components and constants go inside `index.tsx`. Do not create `README.md` or other prose files either — speaker notes / a talk script belong in the `notes` export (see **Speaker notes** below), not in a markdown file.

File contract

// slides/<id>/index.tsx
import type { Page, SlideMeta } from '@open-slide/core';

const Cover: Page = () => <div>…</div>;
const Body: Page = () => <div>…</div>;

export const meta: SlideMeta = {
  title: 'My slide',
  createdAt: '2026-05-16T12:00:00Z',
};
export default [Cover, Body] satisfies Page[];

• `export default` is a **non-empty array of zero-prop React components**, one per page, in order.
• `meta.title` (optional) shows in the slide header. Default is the folder name.
• The slide id is the kebab-case folder name. Pick something short and descriptive (`q2-roadmap`, `team-offsite-2026`).
• `meta.theme` (optional) marks the slide as built from a theme under `themes/`. The id must match a `<id>.md` basename. Surfaces a back-link chip on the slide card and lists the slide on `/themes/<id>`. Omit if the slide isn't derived from a registered theme.
• `meta.createdAt` is an **ISO 8601 string literal** (e.g. `'2026-05-16T12:00:00Z'`) set once when the slide is scaffolded. The home page uses it for the default "newest first" sort. Always include it on new slides — **immediately before writing the file, run `node -e "console.log(new Date().toISOString())"` via Bash and paste the exact output** as the value. Don't type a timestamp from memory — you will get the date or time wrong. Must be a plain string literal (no `new Date(...)` or imports in the slide itself) — the framework reads it via a regex at build time, not by evaluating the module.

Speaker notes (`notes` export)

The framework has **built-in speaker notes**: an optional `notes` export in `index.tsx`, index-aligned with the default page array. The viewer shows them in the notes drawer and present mode shows them in the presenter view next to the timer.

**When the user asks for a speech script, talk track, or presenter notes — in any language — write it into this export, never into a markdown/text file.** A `script.md` or `notes.md` is invisible to the runtime; the `notes` export is the only place the presenter view reads.

export const notes: (string | undefined)[] = [
  'Open with the analyst quote, then introduce yourself.',
  undefined,
  `Walk through the three pillars, one beat each.
Pause for questions before moving on.`,
];

• One entry per page, same order as the `export default` array. `notes[0]` belongs to the first page.
• Entries are **plain text** — line breaks are preserved, markdown is not rendered. Use a template literal for multi-line notes, a normal string for one-l