botharness/deepseekbot/slide-authoring

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:

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-liners.
• Use undefined for a page with no notes; trailing undefined entries can be dropped.
• When you add, remove, or reorder pages, re-align notes in the same edit — a shifted index silently attaches the wrong script to every page after it.
• Write notes as something to say, not a summary of what's on screen: openers, transitions, numbers to cite, timing cues.

Editing an existing slide

A finished slide commonly runs 1000–1800 lines. When you only need to touch one page, don't read the whole file — locate the page first, then read just that range:

grep -n ": Page = " slides/<id>/index.tsx

This lists every const Foo: Page = … declaration with its line number. Read the target page with Read using offset + limit (~150 lines is usually enough to capture one page plus its helper components). Read the whole file only when you need cross-page context (palette audit, reordering, design const tweaks).

Canvas

Every page renders into a fixed 1920 × 1080 canvas. The framework scales it; you design as if the viewport is literally 1920×1080.

• Use absolute pixel values for font-size, padding, positioning. No rem, no vw/vh, no % for type.
• The root element of each page should fill the canvas: width: '100%'; height: '100%'.
• Prefer inline style={{ … }}. Any CSS you load is global — scope classnames carefully.

Type scale (start here, adjust to taste)

Spacing

• Content padding: 100–160px from canvas edges. Never let text touch the edge.
• Line-height: 1.2 for headings, 1.5–1.7 for body.
• Breathing room between elements: 32–64px.

Vertical budget — content MUST fit 1080px

The canvas does not scroll. Anything past the 1080px bottom edge is silently cropped. Before writing JSX, do the math on paper and confirm the page fits. This is the #1 cause of broken slides — assume you will overflow unless you've checked.

Usable height = 1080 − top_padding − bottom_padding. With 120px padding on each side that's 840px. With 160px each side, 760px. Pick the padding first, then design within that budget.

Element height = font_size × line_height × number_of_lines. A bullet that wraps to 2 lines counts as 2 lines. Add the gap below it (32–64px) before summing the next element.

Worked example — single content page, 120px padding (budget = 840px):

Swap the heading to 120px or add a 6th bullet and you're over. Verify every page like this before you write it.

Page-level rules:

• One heading + body OR one heading + ≤5 short bullets. Not both blocks of body copy and a long bullet list.
• A bullet should fit on one line at the chosen font size. If it wraps, either shorten the copy or move it to its own page.
• Hero title pages (140–200px) carry a title + 1 subtitle + maybe an eyebrow — nothing else.
• Section headings (80–120px) need almost nothing else on the page.
• If you find yourself raising padding, shrinking type below the scale's lower bound, or tightening body line-height under 1.4 to make things fit — split into two pages instead. Splitting is always the right answer when the budget is tight.

Never use overflow: auto/scroll, negative margins, or transforms to hide overflow. The canvas is fixed; cropped content is gone.

Visual direction

Pick a coherent look and hold it across every page:

• Palette — 1 background, 1 primary text, 1 accent, 1 muted. Put bg/text/accent in the design const (see Design system below); extra colors like muted stay as plain consts.
• Typography — one display font + one body font. System stack unless the user specifies. Heavy weight for headlines (800–900), normal for body (400–500).
• Layout grid — pick a single content padding (e.g. 120px) and stick to it. Left-aligned content feels editorial; centered feels ceremonial.
• Aesthetic commitment — choose ONE: minimal, maximalist, editorial, retro, brutalist, soft/pastel, neon, paper/print. Don't mix.

If the frontend-design skill is available, consult it for deeper aesthetic guidance when the user wants something bold.

Webfonts

The default is a system font stack — prefer it. When a deck genuinely needs a webfont (a brand font, or CJK / Thai / Arabic where system coverage is poor), read references/webfonts.md first — loading the stylesheet inside a page component registers the whole @font-face set once per mounted page, and CJK families need subsetting.

Themes

If themes/<id>.md exists at the project root and the slide is meant to follow it, the theme file overrides the defaults in this skill — its palette, typography, layout padding, and Title/Footer components are authoritative. Read the theme file before applying anything else in this section.

Themes are produced by the create-theme skill and are pure documentation: copy the palette and the paste-ready Title / Footer / Eyebrow components straight into your slide. If the theme's frontmatter has mode: dark or mode: light, treat that as the slide's background mode (e.g. when picking which logo variant to import).

Design system (opt-in, per-slide)

A slide can declare typed design tokens at the top of index.tsx — export const design: DesignSystem = { palette, fonts, typeScale, radius } — and consume them via var(--osd-X) in inline styles. The framework injects the CSS variables at the canvas root, and the dev UI's Design panel can live-tweak them.

Default to using it. Every new slide should declare a design const so it stays tweakable from the panel after generation. Only fall back to plain palette constants for a one-off slide whose palette is intentionally locked (references/design-system.md covers the fallback).