# Authoring guide

How to turn a user request ("make me a deck about X") into a finished
html-ppt deck. Follow these steps in order.

## 1. Understand the deck

Before touching files, clarify:

1. **Audience** — engineers? designers? executives? consumers?
2. **Length** — 5 min lightning? 20 min share? 45 min talk?
3. **Language** — Chinese, English, bilingual? (Noto Sans SC is preloaded.)
4. **Format** — on-screen live, PDF export, 小红书图文?
5. **Tone** — clinical / playful / editorial / cyber?

The audience + tone map to a theme; the length maps to slide count; the
format maps to runtime features (live → notes + T-cycle; PDF → page-break
CSS, already handled in `base.css`).

## 2. Pick a theme

Use `references/themes.md`. When in doubt:

- **Engineers** → `catppuccin-mocha` / `tokyo-night` / `dracula`.
- **Designers / product** → `editorial-serif` / `aurora` / `soft-pastel`.
- **Execs** → `minimal-white` / `arctic-cool` / `swiss-grid`.
- **Consumers** → `xiaohongshu-white` / `sunset-warm` / `soft-pastel`.
- **Cyber / CLI / infra** → `terminal-green` / `blueprint` / `gruvbox-dark`.
- **Pitch / bold** → `neo-brutalism` / `sharp-mono` / `bauhaus`.
- **Launch / product reveal** → `glassmorphism` / `aurora`.

Wire the theme as `<link id="theme-link" href="../assets/themes/NAME.css">`
and list 3-5 alternatives in `data-themes` so the user can press T to audition.

## 3. Outline the deck

A solid 20-minute deck is usually:

```
cover → toc → section-divider #1 → [2-4 body pages] →
section-divider #2 → [2-4 body pages] → section-divider #3 →
[2-4 body pages] → cta → thanks
```

If the user has no outline, use the **narrative arc** to scaffold one:

```
Hook       → 1 slide    : Contradiction / hard stat / question that stops the room
Context    → 1-2 slides : Who you are · Why this topic · Background
Core       → 3-5 slides : Main substance — vary layouts (data / image / pipeline / quote)
Shift      → 1 slide    : Breaks expectation — new angle, counterintuitive finding
Takeaway   → 1-2 slides : Gold sentence / action item / open question
```

**Theme rhythm — plan before writing any HTML:**

Write out hero vs. body weight for every slide, e.g.:
`1(hero dark) · 2(body) · 3(hero light) · 4(body) · 5(hero dark) · 6(body) · ...`

Rules (all P0 — block delivery if violated):
- Hero and body slides must alternate — no two consecutive heroes
- 3+ slides of the same visual weight in a row = blocked
- Decks ≥ 8 slides: must include ≥1 dark hero and ≥1 light hero

Pick 1 layout per page from `references/layouts.md`. Don't repeat the same
layout twice in a row.

## 4. Scaffold the deck

```bash
./scripts/new-deck.sh my-talk
```

This copies `templates/deck.html` into `examples/my-talk/index.html` with
paths rewritten. Add/remove `<section class="slide">` blocks to match your
outline.

## 5. Author each slide

For each outline item:

1. Open the matching single-page layout, e.g. `templates/single-page/kpi-grid.html`.
2. Copy the `<section class="slide">…</section>` block.
3. Paste into your deck.
4. Replace demo data with real data. Keep the class structure intact.
5. Set `data-title="..."` (used by the Overview grid).
6. Add `<div class="notes">…</div>` with speaker notes.

### Font three-tier rule (apply to every slide)

| Role | Font type | Used for |
|------|-----------|----------|
| Opinion / title | **Serif** (Noto Serif SC / Playfair Display) | Big headlines — signals "this is a claim worth weight" |
| Information / body | **Sans-serif** (Noto Sans SC / Inter) | Body text, bullets, captions — high density, easy to scan |
| Metadata / system | **Monospace** (IBM Plex Mono) | Slide numbers, headers/footers, dates, "Act II · 15/25" — reads like a terminal or magazine page number |

Never use sans-serif for a display-size title. Never use serif for running body text.
These violations are the #1 reason AI-generated slides look amateurish.

### Color discipline

- **Never use pure `#ffffff` or `#000000`.** Use the theme's `--paper` and `--ink` tokens — they are always off-white and off-black (matching Kindle/Monocle aesthetics).
- One accent color maximum per deck (the theme's `--accent`). Don't introduce arbitrary hex values.
- Avoid `color: #xxx` inline — always use `var(--text-1)`, `var(--text-2)`, `var(--surface-1)`, etc.

### Image naming convention

```
ppt/
├── index.html
└── images/
    ├── 01-cover.jpg
    ├── 03-figma.png
    └── 07-dashboard.png
```

- **Zero-pad page numbers** (`01` not `1`) — sorts correctly, AI references unambiguously
- **English semantic names** — short, specific, matches what's on the slide
- **Photos → JPG, UI/transparent → PNG**, min 1600px wide
- **To swap:** drop same filename — HTML unchanged. Only update paths if the filename changes.

## 6. Add animations sparingly

Rules of thumb:

- Cover/title: `rise-in` or `blur-in`.
- Body content: `fade-up` for the hero element, `stagger-list` for grids/lists.
- Stat pages: `counter-up`.
- Section dividers: `perspective-zoom` or `cube-rotate-3d`.
- Closer: `confetti-burst` on the "Thanks" text.

Pick **one** accent animation per slide. Everything else should be calm.

## 7. Chinese + English decks

- Fonts are already imported in `fonts.css` (Noto Sans SC + Noto Serif SC).
- Use `lang="zh-CN"` on `<html>`.
- For bilingual titles, stack lines: `<h1 class="h1">主标题<br><span class="dim">English subtitle</span></h1>`.
- Keep English subtitles in a lighter weight (300) and dim color to avoid
  visual competition.

## 8. Review in-browser

```bash
open examples/my-talk/index.html
```

Walk through every slide with ← →. Press:

- **O** — overview grid; catch any layout clipping.
- **T** — cycle themes; make sure nothing looks broken in any theme.
- **S** — open speaker notes; verify every slide has notes.

## 9. Export to PNG

```bash
# single slide
./scripts/render.sh examples/my-talk/index.html

# all slides (autodetect count by looking for .slide sections)
./scripts/render.sh examples/my-talk/index.html all

# explicit slide count + output dir
./scripts/render.sh examples/my-talk/index.html 12 out/my-talk-png
```

Output is 1920×1080 by default. Change in `render.sh` if the user wants 3:4
for 小红书图文 (1242×1660).

## 10. What to NOT do

- Don't hand-author from a blank file.
- Don't use raw hex colors in slide markup. Use tokens.
- Don't load heavy animation frameworks. Everything should stay within the
  CSS/JS that already ships.
- Don't add more than one new template file unless a genuinely new layout
  type is needed. Prefer composition.
- Don't delete slides from the showcase decks.
- **Don't put presenter-only text on the slide.** Any descriptive text,
  narration cues, or explanations meant for the speaker (e.g. "这一页的重点是…",
  "Note: mention X here", small grey captions explaining the slide's purpose)
  MUST go inside `<div class="notes">`, not as visible elements. The `.notes`
  div is hidden (`display:none`) and only shown via the S overlay. Slides
  should contain ONLY audience-facing content.

## Troubleshooting

- **Theme doesn't switch with T**: check `data-themes` on `<body>` and
  `data-theme-base` pointing to the themes directory relative to the HTML
  file.
- **Fonts fall back**: make sure `fonts.css` is linked before the theme.
- **Chart.js colors wrong**: charts read CSS vars in JS; make sure they run
  after the DOM is ready (`addEventListener('DOMContentLoaded', …)`).
- **PNG too small**: bump `--window-size` in `scripts/render.sh`.