{
  "skill_name": "presentation-creator",
  "evals": [
    {
      "id": 1,
      "prompt": "I'm giving a 25-minute talk at a frontend conference on why design systems fail at scale. Here are my notes (pasted). Turn them into a deck.",
      "expected_output": "A filled story spine with the ending written first, a sectioned outline with a colour per section, per-slide copy, speaker notes, a Marp markdown file, and the slide-by-slide QA table",
      "files": [],
      "assertions": [
        "The spine appears before any slide and names a position a reasonable person could disagree with",
        "Output is Marp markdown with marp: true front matter, --- separators, and notes as HTML comments at the end of each slide, unless the user asked for another format",
        "Headlines are claims, not topic labels (no slide headed 'Overview', 'Background', or 'Metrics')",
        "One colour system throughout: section accents or full-bleed palettes, never both",
        "The QA table has a Contrast column with a numeric ratio per slide, and every body-text pair is at least 4.5:1",
        "Speaker notes are prompts (key point, talk track, transition), not a verbatim script"
      ]
    },
    {
      "id": 2,
      "prompt": "Build me a seed pitch deck for Ledgerline, a bookkeeping tool for freelance designers. 4,200 paying users, $38k MRR, raising $1.5M. I'll email it to investors.",
      "expected_output": "The 10-slide frame with complete-claim headlines, denser standalone copy, an explicit ask slide, no speaker notes, and the QA table using the forwardable test",
      "files": [],
      "assertions": [
        "The traction headline contains the numbers (4,200 users, $38k MRR), not the word 'Traction' alone",
        "There is a Why now slide and an ask slide with amount, use of funds, and next step",
        "No speaker notes are produced, and writing-slides.md copy limits are not applied",
        "The deck is 10 slides plus a separated appendix at most",
        "The QA table substitutes the forwardable test for the 3-second test"
      ]
    },
    {
      "id": 3,
      "prompt": "Here's my deck outline for the all-hands (pasted). It's fine but it has no story, it's just a list of updates. Fix it.",
      "expected_output": "A story spine derived from the existing content, the slides re-sequenced or cut against the spine, with cuts named",
      "files": [],
      "assertions": [
        "A filled spine is produced before any slide is edited",
        "At least one existing slide is cut or merged with the reason 'serves no spine beat'",
        "The ending is written before the middle is reordered"
      ]
    },
    {
      "id": 4,
      "prompt": "Presenting tomorrow in a glass-walled meeting room at 2pm with a cheap projector. Design the slides for my deck (copy attached).",
      "expected_output": "A light-palette design pass: paper or white background with near-black text and the section accents, with the reason stated",
      "files": [],
      "assertions": [
        "The dark system is not chosen by default; the venue is cited as the reason for a light palette",
        "Body text contrast is stated numerically and is at least 4.5:1",
        "Type sizes are given in pt or Marp px, not clamp(), because the output is a fixed canvas"
      ]
    },
    {
      "id": 5,
      "prompt": "Turn this deck into a PowerPoint file my client can edit. It's currently Marp markdown.",
      "expected_output": "A handoff to the external pptx skill with the outline, copy, notes, and colour and type spec, not a marp-cli --pptx export",
      "files": [],
      "assertions": [
        "The response does not present marp --pptx or slidev export --format pptx as the deliverable, and explains that those produce image slides",
        "The pptx skill is invoked or named, with notes routed to the notes pane",
        "This skill's colour system and type hierarchy are passed along, translated to pt"
      ]
    }
  ],
  "routing": {
    "should_trigger": [
      "Outline a presentation about our migration from monolith to services for the engineering all-hands.",
      "Write slides for a 10-minute lightning talk on CSS container queries.",
      "Design a deck for our Q3 board update, dark theme, something with more personality than the template.",
      "Turn this product spec into a deck I can walk the sales team through.",
      "Build a pitch deck for investors; we're raising a $2M seed.",
      "My talk has no story, it's just a list of features. Help.",
      "Write my speaker notes for these 18 slides.",
      "Build this deck as a website with a live demo on slide 6."
    ],
    "near_miss": [
      { "prompt": "Write the hero copy and CTA for the landing page we're launching alongside the talk.", "expected": "copywriting" },
      { "prompt": "Build a landing page for the conference with a dark theme and a speaker grid.", "expected": "ui-design" },
      { "prompt": "Open quarterly-review.pptx and pull the text out of every slide into a summary.", "expected": "pptx (external)" },
      { "prompt": "Write a 2,000-word blog post version of my conference talk.", "expected": "ghostwriter (external, platform blog)" },
      { "prompt": "Make a bar chart of our monthly revenue for the traction slide.", "expected": "dataviz (external)" }
    ]
  }
}

# Outline Structure

Define the narrative arc and slide sequence before writing copy.

## Contents

- [Standard flow](#standard-flow)
- [Slide types](#slide-types)
- [Section colors](#section-colors)
- [Output format](#output-format)

## Standard flow

```
Opening → Context / Problem → Core Sections (2-4) → Closing
```

- **Opening**: title, goals/agenda (3 takeaways max)
- **Context**: current state, the tension or question to resolve
- **Core sections**: 3-5 content slides each, dividers between topics
- **Closing**: recap (one line per section), resources, Q&A

Every slide earns its place against one of the three key messages; cut the ones that only add facts.

## Slide types

| Type | Purpose | Example |
|------|---------|---------|
| **statement** | Land a key point | "Speed is a feature" |
| **big-statement** | Maximum impact, one idea | "AI has no memory" |
| **question** | Create tension | "What would we do differently?" |
| **section-divider** | Signal topic shift | "Where we play" |
| **goals** | Set expectations | "Goals for today" |
| **data** | Prove with numbers | "3x growth in 6 months" |
| **code** | Show implementation | Syntax-highlighted block |
| **framework** | Model or comparison | Do's and don'ts, matrix |
| **quote** | Borrow authority | "What got you here won't get you there" |
| **recap** | Summarize before close | Key takeaways |
| **resources** | Link references | Grouped by section |
| **next-steps** | Drive action | "Where to from here?" |

## Section colors

One accent per major section. Reinforces structure, helps the audience track position.

| Color | Hex | Typical use |
|-------|-----|-------------|
| Teal | #14b8a6 | Opening, framing, recap |
| Red | #f87171 | Problems, challenges, tension |
| Purple | #a78bfa | Solutions, features, tools |
| Amber | #fbbf24 | Data, reality checks, caveats |
| Green | #34d399 | Best practices, what works |
| Blue | #60a5fa | Technical, implementation |
| Pink | #f472b6 | Highlights, special callouts |

## Output format

```markdown
# [Presentation Title]
[One-line purpose]

---

## 1. Opening
**Color:** teal

### Slide 1: Title
- **Type:** statement
- **Headline:** [Title]
- **Subtitle:** [Context or date]

### Slide 2: Goals for today
- **Type:** goals
- **Headline:** Goals for today
- **Points:**
  - [Takeaway 1]: [Brief explanation]
  - [Takeaway 2]: [Brief explanation]
  - [Takeaway 3]: [Brief explanation]

---

## 2. [Section Name]
**Color:** [color]

### Slide 3: Section divider
- **Type:** section-divider
- **Headline:** [Section title]

### Slide 4: [Slide purpose]
- **Type:** [statement/data/code/etc.]
- **Headline:** [Bold headline]
- **Supporting:** [1-2 sentences or bullets]

---

## N. Closing
**Color:** teal

### Slide N: Recap
- **Headline:** Recap
- **Points:** [One-liner per section]
```

# Output Formats

Emit the finished deck. Marp markdown is the default; Slidev and reveal.js are the swaps when the user already runs one; a `.pptx` is a handoff to the external `pptx` skill. Read this at Step 7, once copy and notes exist.

## Contents

- [Pick a format](#pick-a-format)
- [Marp (default)](#marp-default)
- [Slidev](#slidev)
- [reveal.js](#revealjs)
- [Handing off to the pptx skill](#handing-off-to-the-pptx-skill)
- [Gotchas](#gotchas)

## Pick a format

| Situation | Format |
|-----------|--------|
| No format named, no live demo needed | Marp markdown: one `.md` file, renders to HTML, PDF, and PPTX, previews in VS Code |
| The user already has a Slidev or reveal.js deck, or wants Vue components on slides | Match what they run; syntax below |
| A live demo, a playground, or a deck that lives at a URL | Web app, `web-deck.md` |
| The user names a `.pptx` or `.potx`, or must edit in PowerPoint or Keynote | External `pptx` skill, fed from this skill's outline, copy, and notes |
| A deck sent to be read (investor pitch) | Marp to PDF, or `pptx` when the recipient expects PowerPoint |

## Marp (default)

Front matter turns the file into a deck; `---` on its own line separates slides; a slide's presenter note is an HTML comment at the end of that slide.

```markdown
---
marp: true
theme: default
size: 16:9
paginate: true
style: |
  section { background: #000; color: #fff; font-family: Inter, system-ui, sans-serif; }
  section.accent-teal h1 { color: #14b8a6; }
---

<!-- _class: lead accent-teal -->

# <!-- fit --> AI has no memory

Every session starts from zero

<!-- Open with the outage story. Pause after the headline. -->

---

<!-- _class: accent-red -->

## The bottleneck moved

- **Code got cheap.** Agents write it faster than we review it.
- **Judgement did not.** Nobody tooled for it.

<!-- Transition: "so where does the leverage go?" -->
```

Directive mechanics that matter:

- Global directives (`theme`, `size`, `style`, `math`) go in the front matter once. `size` accepts `16:9` (1280x720) and `4:3` (960x720).
- Local directives apply from the current slide onward (`<!-- paginate: true -->`); an underscore prefix makes a spot directive for the current slide only (`<!-- _class: lead -->`, `<!-- _backgroundColor: #e54f11 -->`). Section colours are spot `_class` directives, one per slide, styled in the front-matter `style` block.
- `# <!-- fit --> Headline` scales a heading to the slide width: the big-statement slide.
- A comment is a directive when its body parses as `key: value` lines, otherwise a presenter note. Start notes with a sentence, not a colon-separated pair.

Export with marp-cli. PDF, PPTX, and images need Chrome, Edge, or Firefox installed:

```bash
npx @marp-team/marp-cli deck.md -o deck.html
npx @marp-team/marp-cli deck.md --pdf --pdf-notes -o deck.pdf
npx @marp-team/marp-cli deck.md --notes -o notes.txt
```

## Slidev

Same skeleton: headmatter, `---` separators, per-slide front matter for layout, HTML comment at the end of the slide for the note.

```markdown
---
theme: default
---

# AI has no memory

Every session starts from zero

<!-- Open with the outage story. -->

---
layout: two-cols
---

# The bottleneck moved

::right::

- **Code got cheap.**
- **Judgement did not.**
```

`v-click` on a list item reveals it on the next keypress; use it for a build, not for decoration. Export needs `playwright-chromium`: `slidev export` (PDF), `slidev export --format pptx`, `--format png`. Interactive components do not survive export; a deck built for them is a web deck, hosted, not exported.

## reveal.js

Markdown lives inside `<section data-markdown><textarea data-template>`; the horizontal separator defaults to a `---` line; speaker notes start on a `Note:` line at the end of the slide, read by the speaker view (`s` key). The HTML shell is the deck, so a reveal.js deck is a small web project, not a single file.

## Handing off to the pptx skill

The `pptx` skill builds and edits the file; this skill decides what goes on each slide. Hand it, in one message:

1. The outline from `outline-structure.md` with the section colour on every divider
2. The per-slide copy (headline, body) from Step 4
3. The speaker note for each slide, to go into the notes pane, never into a text box on the slide
4. The colour system and type hierarchy from Step 5, translated to pt (`visual-design.md` has the fixed-canvas scale)

Where its defaults differ from this skill's (bold titles, a visual on every slide), this skill's direction wins on colour and type hierarchy, and its mechanics win on safe fonts, margins, notes, and QA rendering. Hand over the whole deck at once: a slide-by-slide handoff loses the section colour rhythm.

## Gotchas

- `--pptx` from Marp and `--format pptx` from Slidev rasterise every slide to an image inside the `.pptx`. Text is not selectable, searchable, or editable. `--pptx-editable` in marp-cli is experimental and loses styling. When the recipient needs to edit, use the `pptx` skill.
- A Marp presenter note whose first line looks like `Key point: speed` is parsed as a directive and vanishes from the notes export. Write `The key point is speed.` or move the colon.
- `marp: true` is what Marp for VS Code keys on; without it the file previews as plain markdown and the `---` lines render as horizontal rules.
- A Marp `style` block that sets `section` colours also needs `h1`, `h2`, `a`, and `code` colours: theme defaults are built for a light background and leave dark-blue links on a black slide.
- reveal.js `---` separators need blank lines on both sides in external markdown, or the file renders as one slide.

# Pitch Decks

Investor pitch decks that work without a presenter: denser copy, an expected structure, optimised for a reader skimming on a laptop. The 10-slide frame is the common ground between Kawasaki's 10/20/30 rule, Sequoia's business-plan outline, and YC's seed deck guidance; the async copy rules are this skill's.

## Two pitch decks, not one

| Aspect | Sent deck (this file) | Presented deck (demo day, partner meeting) |
|--------|-----------------------|--------------------------------------------|
| Who reads it | An associate skimming at a desk, then forwarding it | A room, with you talking |
| Text density | Higher: every slide stands alone | Minimal: one idea, large type, you add the rest |
| Reading time | 30-60 sec per slide, studied | 3 sec per slide, glanced |
| Font floor | Legible at 50% zoom | 30pt body (Kawasaki), legible from the back row (YC) |
| Structure | The 10-slide frame, in order | The same frame, presented in 20 minutes or less |
| Copy rules | This file | `writing-slides.md`, with this frame as the outline |

Build the sent deck first. The presented version is a cut of it with the body text moved into the talk track.

## The 10-slide frame

Order is flexible where a slide is unusually strong (traction early when the numbers carry the story), fixed otherwise: readers expect it, and a Problem slide on page 7 reads as evasion.

### 1. Title
Company name, the company in one declarative sentence (Sequoia's "company purpose"), contact. Optional one-line traction hook.

### 2. Problem
Who feels the pain, why it is urgent, what they do about it today. Lead with a customer quote or a number.

### 3. Solution
Product in 30 seconds, as before and after, not a feature list. One screenshot at most.

### 4. Why now
What changed that makes this possible or necessary this year. Sequoia's question; a deck with no answer reads as a good idea anyone could have had five years ago.

### 5. Traction
Charts over text: revenue, users, growth rate, retention, logos. Put the number in the headline.

### 6. Market
Bottom-up TAM/SAM/SOM from customers times price, not a quoted "$1T market".

### 7. Business model
Revenue streams, pricing, unit economics (CAC, LTV, payback).

### 8. Competition
A landscape matrix or quadrant with your axis of differentiation. "No competition" reads as "no market".

### 9. Team
Names, roles, one line of relevant credential each. Why this team wins this market.

### 10. The ask
Amount, use of funds, the milestones it unlocks, next step.

```
**Raising:** $XM [Stage]
**Use of funds:**
- 50% Product
- 30% Go-to-market
- 20% Operations
**Unlocks:** [milestone] by [date]
**Next step:** 30-minute call
```

Financial projections and roadmap go in an appendix after the ask, clearly separated. Anything beyond 10 slides plus appendix is trimming, not adding.

## Writing for async reading

- Headlines are the complete claim: "1,000+ customers, $10M ARR", not "Traction". The forwardable test: does the headline alone make sense to someone who received this with no context?
- 2-3 bullets per section, each a complete thought. Bold the key phrase, explain after.
- Charts over tables over bullets over paragraphs.
- Metrics as text on the slide, not baked into an image: search, screen readers, and the associate's copy-paste all read text. Define acronyms on first use; slide titles match the expected categories so a skimmer finds Traction where they look for it.

## Common mistakes

| Mistake | Fix |
|---------|-----|
| No clear ask | Explicit slide with amount, use, milestones, next step |
| Features over benefits | Lead with the outcome for the customer |
| TAM fantasy | Bottom-up calculation from customers times price |
| No traction proof | Chart, logos, or testimonials; a number in the headline |
| Too many slides | The 10-slide frame; everything else in a separated appendix |
| Presented-deck copy in a sent deck | Every headline passes the forwardable test |

## Format guidelines

- **PDF for sending:** under 10MB, named `Company - Stage Deck - Month Year.pdf`. Marp to PDF (`output-formats.md`), or the external `pptx` skill when the recipient expects PowerPoint
- **16:9**, high contrast, readable at 50% zoom
- Same colour systems and contrast thresholds as presented decks (`visual-design.md`); a sent deck is read on a laptop in daylight, so the paper or near-black pairs suit it better than pure black

# Speaker Notes

Scannable prompts for natural delivery, not scripts to read verbatim.

## Per-slide note structure

```markdown
### Slide [N]: [Headline]

**Key point:** [The ONE thing they must remember]

**Open with:** [First sentence or hook, conversational tone]

**Talk track:**
- [Prompt 1]
- [Prompt 2]
- [Optional anecdote or example]

**Transition:** [Bridge to next slide]
```

### Example

```markdown
### Slide 5: Speed is a feature

**Key point:** Being fast is a competitive advantage, not just a nice-to-have.

**Open with:** "This slide captures something we keep rediscovering..."

**Talk track:**
- Every time we ship faster, customers notice and tell us
- Our competitors take months for changes we do in days
- Speed compounds, fast shipping builds momentum and morale

**Transition:** "So how do we protect that speed as we scale?"
```

## Notes by slide type

**statement / question**: Expand on the headline: what led to this conclusion, what's the implication. For questions, pause and let it land before answering.

**data**: Contextualize the numbers: what story do they tell? What surprised you?

**section-divider**: Brief: quick framing of what's coming, how it connects to what came before.

**recap**: Don't re-present. Touch each point quickly, add one synthesis insight, set up "so what."

## Delivery cues

Include when relevant:
- **(pause)**: let a point land
- **(show of hands)**: audience interaction
- **(click)**: advance animation or build
- **(emphasize)**: vocal stress on key word
- **(scan room)**: make eye contact before transitioning

## Where the notes go

The output format reads notes from one place each: Marp and Slidev take an HTML comment at the end of the slide, reveal.js a `Note:` line, a `.pptx` the notes pane (never a text box on the slide). `output-formats.md` has the syntax. Keep the structure above inside that slot; the headings become plain lines in a Marp comment, and a first line shaped like `Key point: X` parses as a Marp directive, so write it as a sentence.

## Context adjustments

- **Internal**: informal, reference shared history, challenge directly, be candid about what's hard
- **External**: build credibility first, prove before concluding, leave room for questions
- **Recorded/async**: tighter, less tangential, stronger signposting; notes clarify what's not obvious from slides alone

# Story Structure

An outline sequences slides. A story makes the audience want the next one. Do this before the outline: the spine decides which slides exist.

Adapted from the 22 rules of storytelling that Pixar storyboard artist Emma Coats posted in 2011. The spine itself (rule 4 on her list) is older: improviser Kenn Adams wrote it in 1991 as a teaching tool, and it reached Pixar through its improv classes. Both were written for stories on a stage or a screen, and they transfer to talks because a talk has the same problem: a room that can leave at any moment.

## Contents

- [The spine](#the-spine)
- [Find the story before the slides](#find-the-story-before-the-slides)
- [Make the audience want the next slide](#make-the-audience-want-the-next-slide)
- [When you are stuck](#when-you-are-stuck)
- [Knowing when to stop](#knowing-when-to-stop)
- [Output](#output)

## The spine

Fill this in, in one sitting, before any slide exists:

```text
Once upon a time ___.
Every day ___.
One day ___.
Because of that ___.
Because of that ___.
Until finally ___.
```

Mapped onto a deck:

| Beat | The deck's job | Slides |
|------|----------------|--------|
| Once upon a time | The world the audience already lives in | Opening, framing |
| Every day | The status quo, stated plainly enough that they nod | Context |
| One day | What changed, or the question that breaks the status quo | The tension slide |
| Because of that | The consequence, and the consequence of that | Core sections |
| Until finally | Where it lands, and what they do about it | Close, next steps |

A worked spine, from a talk on tooling for coding agents:

> Once upon a time writing code was the expensive part. Every day we optimised for typing less of it. One day agents made code cheap. Because of that the bottleneck moved to judgement, which nobody had tooled for. Because of that the only leverage left was encoding your taste where the agent reads it. Until finally the tools you build for yourself are the thing worth giving away.

If a slide does not serve a beat, it is a fact you found interesting. Cut it.

## Find the story before the slides

**Write the ending first.** Endings are hard. Get yours working before the middle, or you will build five sections toward a close that does not exist yet and rewrite all of them.

**Ask why this story.** What is the belief burning underneath? That is the heart of it, and it is also the answer to why you are the one on stage. A deck with no answer here becomes a summary, and a summary can be an email.

**Discount the first idea. And the second, third, fourth, fifth.** The first structure that comes to mind is the one everyone in the room has already seen. Get the obvious out of the way on paper, then look at what is left.

**Take apart a talk you loved.** What you like in it is a part of you, and you cannot use it until you can name it. Name the move, then find where it fits your spine.

**Put it on paper.** A perfect deck in your head is unfixable. A rough one on paper can be fixed today.

## Make the audience want the next slide

**Give the deck an opinion.** A passive deck that surveys the landscape feels safe to write and is poison to an audience. Take a position that a reasonable person could disagree with. If nobody could disagree, you have not said anything.

**Name the stakes.** What happens if they do nothing? What does the room lose? Stack the odds against your own argument and then answer it; a claim that never met resistance reads as unearned.

**Admire the trying, not the winning.** An audience roots for the attempt. A deck that only shows the finished result skips the part they connect to. The failed version, the thing that took three tries, the constraint you worked around: those are the slides people remember.

**Throw the opposite at your subject.** If your thesis is comfortable in one setting, show it where it should break. How it holds up there is the proof; how it fails is the honest caveat that buys trust for everything else.

**Coincidence rule.** A surprising fact may open a problem. It may never resolve one. If a section ends with "and then it turned out fine", the audience is being asked to accept a conclusion the slides did not earn.

**Honesty for the unbelievable parts.** If you were sitting where the audience is, what would you not believe? Say that out loud, then answer it.

## When you are stuck

**List what WOULDN'T happen next.** The most useful of the 22 rules. Write five things that could not follow from the slide you are stuck on. The blocked feeling comes from circling one obvious continuation; naming its opposites usually surfaces the material.

**Simplify, focus, combine, hop over detours.** Merge two sections that make one point. Cut the setup for a payoff you removed. It will feel like losing something valuable and it will set the deck free.

**Move on if it is not working.** No work is wasted. A section that will not come together goes in a notes file and often comes back useful in the next talk.

## Knowing when to stop

Story is testing, not refining. You learn what the deck is about by running it end to end against a clock, not by polishing slide four for the ninth time. Get a rough version complete, run it out loud, then rewrite from what you learned: the theme you were trying for only becomes visible at the end of the first full run.

## Output

Add this above the outline, before any slide is written:

```markdown
## Spine

- **Once upon a time:** [the world they live in]
- **Every day:** [the status quo]
- **One day:** [what changed]
- **Because of that:** [first consequence]
- **Because of that:** [second consequence]
- **Until finally:** [where it lands]

**Why this story:** [the belief underneath]
**The position:** [what a reasonable person could disagree with]
**The stakes:** [what the audience loses by doing nothing]
**The ending, written first:** [the final slide, verbatim]
```

# Visual Design

High contrast, minimal, impact from scale rather than decoration. Two colour systems, one type system, one set of layouts.

## Contents

- [Pick a colour system](#pick-a-colour-system)
- [Contrast thresholds](#contrast-thresholds)
- [Full-bleed palettes](#full-bleed-palettes)
- [Dark with section accents](#dark-with-section-accents)
- [Typography hierarchy](#typography-hierarchy)
- [Layout patterns](#layout-patterns)
- [Slide type to layout mapping](#slide-type-to-layout-mapping)
- [Visual elements](#visual-elements)
- [Avoid](#avoid)

## Pick a colour system

Decide once, at the start of the design step, and hold it for the whole deck.

| System | Use it when | How the audience tracks position |
|--------|-------------|----------------------------------|
| **Full-bleed palettes** | The deck has a visual identity of its own, or covers distinct products, tools, or chapters that each own a colour | The whole screen changes |
| **Dark with section accents** | Technical content, heavy code and data, a dark room or large hall, or a house template you have to live inside | An accent colour changes |

Dark with accents is the default and never looks wrong in a dark room. Full-bleed is the bolder choice and the harder one to execute, because every pairing has to carry body text at real contrast.

The venue overrides the default. Duarte's rule of thumb: dark backgrounds suit formal settings and large venues where the screen glows; light backgrounds suit small bright rooms and anything that doubles as a handout. A dark deck on a weak projector in daylight goes grey, and white body text disappears into it. When Step 1 says bright room, run the dark system's roles inverted (paper `#f6ebd9` or white background, near-black `#211f1e` text, the same section accents) or pick the full-bleed paper pair for most slides.

## Contrast thresholds

WCAG 1.4.3, applied to slides: 4.5:1 between text and background for normal text, 3:1 for large text, where large means at least 18pt (24px) or 14pt (18.66px) bold. In practice only headlines and big statements qualify as large; body, bullets, captions, and code all need 4.5:1. Measure from the hex values, not from how it looks on your screen, and check the smallest text on the slide. A pair that passes at headline size and fails at caption size is a failing pair.

Projection is harsher than the standard assumes. Ambient light lifts the black level, so treat 4.5:1 as the floor and prefer 7:1 for body text on the dark system (`#FFFFFF` on `#000000` is 21:1; `#9CA3AF` muted on `#18181b` is 7.0:1).

## Full-bleed palettes

One palette owns the entire slide. Background, foreground, and the muted tone all come from the same pair. There is no accent colour, because the slide is the accent.

Drive it from a data attribute so a slide declares its palette and nothing else has to know:

```css
[data-palette="rust"] {
  --bg: #e54f11;
  --fg: #ffffc2;
  --fg-soft: color-mix(in oklab, var(--fg) 80%, var(--bg));
  --hairline: color-mix(in oklab, var(--fg) 22%, var(--bg));
}
```

Derive the muted tone with `color-mix` against the background, not with opacity. Opacity muddies against a saturated background and gives you a different hue on every slide.

Pairs that hold up at display size, with the body-text contrast you are working with:

| Background | Foreground | Ratio | Reads as |
|------------|------------|-------|----------|
| `#e54f11` | `#ffffc2` | 3.7:1 | Rust on cream, loud. Headlines only; body text fails 4.5:1, so keep captions off this slide or lift the foreground |
| `#f6ebd9` | `#514733` | 7.7:1 | Paper, the quiet slide between loud ones, and the bright-room fallback |
| `#0c90d2` | `#aeffff` | 3.1:1 | Blue on cyan, high energy. Headline slides only |
| `#211f1e` | `#f6ebd9` | 13.9:1 | Near-black on warm white, the workhorse |
| `#efee77` | `#000000` | 17.2:1 | Yellow, use once |

Rules that keep it coherent:

- **A subject keeps its palette.** Every slide about one product, tool, or chapter uses the same pair. That run of colour is the wayfinding.
- **Loud, then quiet.** Two saturated slides in a row exhaust the room. Put a paper or near-black slide between them.
- **The loud pairs carry headlines, the quiet pairs carry body.** Rust and blue sit under 4.5:1 and belong on statement and divider slides; anything with bullets or captions goes on paper or near-black.
- **Borders come from the pair.** A hairline is `--fg` mixed into `--bg`, never a grey.

## Dark with section accents

The alternative system. Black or zinc-900 throughout, white text, one accent per major section.

| Element | Spec |
|---------|------|
| Background | `#000000` or zinc-900 (`#18181b`) |
| Text primary | `#FFFFFF` |
| Text secondary / muted | `#9CA3AF` (7.0:1 on zinc-900, 9.0:1 on black) |
| Accents | Section colours, listed with the section table in outline-structure.md; all seven sit above 7.5:1 on black and 6.4:1 on zinc-900, so an accent can carry a headline or a bold lead-in, but muted `#9CA3AF` stays the caption colour |
| Font | Sans-serif (Geist Sans, Inter, or system) |
| Code font | JetBrains Mono or Fira Code |
| Letter spacing | Headlines: -0.035em to -0.015em. All caps labels: tracked wide |

One accent per major section, teal reused for opening and closing. An accent that appears mid-section reads as a topic change that never happened.

## Typography hierarchy

Impact through **scale, not weight**: light and regular weights at large sizes beat small bold type.

### Fluid scale (web deck)

Size in `clamp()`, not fixed pixels. A deck is presented on a projector, reviewed on a laptop, and forwarded to a phone; a fixed 72px headline is a different slide on each.

```css
--slide-text-sm:      clamp(12px, 0.8vw, 16px);
--slide-text-base:    clamp(14px, 0.95vw, 20px);
--slide-text-lg:      clamp(16px, 1.1vw, 24px);
--slide-text-2xl:     clamp(22px, 1.6vw, 36px);
--slide-text-4xl:     clamp(34px, 2.5vw, 56px);
--slide-text-6xl:     clamp(56px, 5vw, 110px);
--slide-text-display: clamp(64px, 9vw, 200px);
```

### Fixed canvas (Marp, Slidev export, .pptx)

A 16:9 canvas is 1280x720 in Marp and 13.33x7.5in in PowerPoint, so sizes are absolute. Translate the steps:

| Level | Fluid step | Marp px | PowerPoint pt |
|-------|-----------|---------|---------------|
| Caption / section label | `sm` | 16-18 | 12-14 |
| Body / bullets | `lg` | 24-28 | 18-24 |
| Subtitle | `2xl` | 32-36 | 24-28 |
| Headline | `4xl` to `6xl` | 56-96 | 40-66 |
| Big statement | `display` | `<!-- fit -->` | 80+ |

Two floors: Kawasaki's 30pt for body text on a presented pitch in a large room, 18pt for a deck read at a desk.

### Levels

| Level | Weight | Colour | Use |
|-------|--------|--------|-----|
| Section label | 600, all caps | Accent or `--fg-soft` | Top-left, signals current section |
| Headline | 400-500 | `--fg` | One idea, 1-5 words per line |
| Big statement | 400-500 | `--fg` | One or two per deck, no more |
| Subtitle | 400 | `--fg-soft` | 1-2 lines max |
| Body / bullets | 400-500 | `--fg` or `--fg-soft` | Bold lead-ins at 600 |
| Caption | 400 | `--fg-soft` | Footnotes, sources |

Set headlines with `text-wrap: balance`, `line-height` near 0.95, and negative tracking around -0.025em. At display size the default line-height leaves a hole in the middle of the slide.

A variable typeface earns its place here: animating weight and tracking as a headline settles is the one motion effect that reads as craft rather than decoration.

## Layout patterns

Statement, big-statement, and section-divider layouts follow the [mapping table](#slide-type-to-layout-mapping): label top-left, headline scaled to fill, subtitle muted. The diagrams below cover only layouts with real spatial arrangement.

### Split layout (text + content)

Asymmetric ratios read better than 50/50. Pick from a fixed set (60/40, 70/30, 40/60, 30/70) so the deck stays consistent, with an optional hairline between columns.

```
┌────────────────────┬────────────────────┐
│                    │                    │
│ Headline           │  • Point one       │
│ Here               │  • Point two       │
│                    │  • Point three     │
│ Subtitle           │                    │
└────────────────────┴────────────────────┘
```

### Code slide
```
┌─────────────────────────────────────────┐
│ Headline                                │
│ Subtitle                                │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ // syntax-highlighted code block    │ │
│ │ const result = await generate()     │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```

### Data/metrics
```
┌─────────────────────────────────────────┐
│        ┌────────┐ ┌────────┐ ┌────────┐ │
│        │  $10M  │ │  ~10%  │ │  NPS   │ │
│        │  ARR   │ │ GROWTH │ │   90   │ │
│        └────────┘ └────────┘ └────────┘ │
│ Headline                                │
│ Subtitle                                │
└─────────────────────────────────────────┘
```

## Slide type to layout mapping

| Slide type | Layout |
|------------|--------|
| statement | Full statement, left-aligned |
| big-statement | Big statement, centered |
| question | Full statement, centered |
| section-divider | Full-bleed palette change, or accent gradient on the dark system |
| goals, recap | Split layout or full statement with bullets |
| data | Data/metrics grid; the chart itself is `dataviz` territory where that skill is installed |
| code | Code slide with syntax highlighting |
| demo | Full-bleed, the running thing, minimal chrome |
| quote | Big statement with attribution below |
| resources | Grouped links, split layout |

Vary the layout when the slide's job changes. A section that is genuinely a list of three parallel points can hold one layout for three slides; a deck that holds one layout for ten has stopped signalling anything.

## Visual elements

- **Section labels**: top-left, all caps, tracked wide
- **Oversized numerals**: the slide number set large in `--fg-soft` as marginalia, a cheap way to fill a corner without decoration
- **Pill labels**: outlined or solid, drawn from `--fg`, for a category or a product name
- **Progress bar**: bottom edge, thin (3px)
- **References**: bottom footer, clickable URLs, muted
- **Icons**: simple line icons, `--fg` or accent, used sparingly

## Avoid

- A palette pair that fails 4.5:1 at body size because it passed at headline size
- Opacity where `color-mix` against the background belongs
- Heavy font weights for headlines (use scale)
- Fixed pixel type in a web deck that will be viewed at more than one size
- Mixing the two colour systems: an accent colour on a full-bleed palette slide
- Multiple competing focal points
- Dense paragraphs
- Animation for its own sake

# Web Deck

Building the deck as a web app instead of exporting it from a deck tool. Written for Next.js App Router; the structure transfers to any router.

The reason to do it: the deck can run the thing it is about. Everything else here is in service of that.

## Contents

- [When a web deck is worth it](#when-a-web-deck-is-worth-it)
- [One array as the source of truth](#one-array-as-the-source-of-truth)
- [A route per slide](#a-route-per-slide)
- [Navigation](#navigation)
- [Primitives, not bespoke markup](#primitives-not-bespoke-markup)
- [Motion](#motion)
- [Live demos](#live-demos)
- [Sharing and metadata](#sharing-and-metadata)
- [Gotchas](#gotchas)

## When a web deck is worth it

Worth it when at least one is true:

- Something in the deck should be interactive: a working demo, a playground, a live query
- The deck is a permanent artefact with a URL, not a file emailed once
- The design is specific enough that a template fights you

Not worth it for an internal update, a deck someone else has to edit, or anything due tomorrow. A deck tool is faster and the audience cannot tell.

## One array as the source of truth

Slide order, titles, and palettes live in one place. Everything else derives from it: the route params, the counter, the outline page, the metadata.

```ts
export const SLIDES = [
  { slug: "intro", title: "Care made easy", palette: "e" },
  { slug: "thesis", title: "The bottleneck has changed", palette: "e" },
  { slug: "sync-demo", title: "Apps that just work", palette: "stratasync" },
] as const satisfies readonly { slug: string; title: string; palette: Palette }[];

export const TOTAL_SLIDES = SLIDES.length;
```

`as const satisfies` is the part that pays: the palette on every slide is checked against the union of defined palettes, so a typo is a build error rather than an unstyled slide discovered on stage.

## A route per slide

`/7` opens slide 7. That is worth more than it sounds: you can link a colleague to the one slide you want reviewed, restart mid-talk without arrowing through 20 slides, and let the browser back button behave.

```tsx
export function generateStaticParams() {
  return SLIDES.map((_, i) => ({ slide: String(i + 1) }));
}

export default async function SlidePage({ params }: { params: Promise<{ slide: string }> }) {
  const slideNum = Number.parseInt((await params).slide, 10);
  if (Number.isNaN(slideNum) || slideNum < 1 || slideNum > TOTAL_SLIDES) notFound();

  const SlideContent = slideComponents[slideNum - 1];
  return (
    <SlideNavigation currentSlide={slideNum} palette={SLIDES[slideNum - 1].palette} totalSlides={TOTAL_SLIDES}>
      <SlideContent />
    </SlideNavigation>
  );
}
```

Statically generate all of them. A slide that compiles on demand is a black screen in front of a room.

## Navigation

Arrow keys, plus a visible control for touch. Route with `scroll: false` so the browser does not jump on transition. `useHotkeys` below is from `react-hotkeys-hook`; a `keydown` listener does the same job.

```tsx
useHotkeys("right", goNext, { preventDefault: true }, [goNext]);
useHotkeys("left", goPrev, { preventDefault: true }, [goPrev]);
```

Make the counter accessible: it is the only thing telling a screen reader the position changed.

```tsx
<span aria-live="polite" className="tabular-nums">
  <span className="sr-only">Slide </span>
  {currentSlide}
  <span className="sr-only"> of </span>
  <span aria-hidden="true"> / </span>
  {totalSlides}
</span>
```

`tabular-nums` stops the counter jittering as the number changes width. Disable the prev and next buttons at the ends rather than wrapping around; wrapping past the last slide during Q&A is worse than a dead key.

## Primitives, not bespoke markup

Twenty hand-built slides drift by slide six. A handful of primitives keeps them one deck:

| Primitive | Job |
|-----------|-----|
| `Stage` | Full-bleed surface, sets `data-palette`, owns `min-h-dvh` |
| `Display` | The headline. One per slide, sized by a named step |
| `Split` | Two columns at a named ratio, optional hairline |
| `Block` | Bordered region, replaces the UI kit's Card on a slide |
| `Mark` | Pill label for a category or product name |
| `Numeral` | Oversized zero-padded number as marginalia |
| `KineticList` | Staggers its children on enter |

Each takes an enum, not a className: `ratio="60/40"`, `size="display"`, `tone="outline"`. The enum is what stops slide 14 from being 63/37.

Use `min-h-dvh` rather than `h-screen`. Mobile browser chrome makes `100vh` wrong on the device most people will forward the deck to.

## Motion

Two effects earn their place. Enter animations only, since there is no exit worth watching.

- **Headline settle**: on a variable typeface, animate weight and tracking from light and loose to heavy and tight over the first few hundred milliseconds. The one motion effect that reads as craft.
- **Staggered rise**: list items fade up on a per-index delay, `calc(var(--stagger-i) * 50ms + 80ms)`. Set the index as a CSS variable rather than an inline delay so the stagger is data, not markup.
- **Nothing else by default.** A slide transition or parallax has to justify itself against the headline settle; it almost never does.

## Live demos

The whole reason for the format. A working sync demo, not a screenshot of one. A typeface playground the audience watches you drag. An inspector that reads styles off the slide it is sitting on.

Rules that keep a demo from eating the talk:

- **It runs offline.** In-memory transport, seeded data, no network. Conference wifi is the single most common way a demo dies.
- **It resets on mount.** You will show it twice.
- **It survives being poked.** Someone will click it during Q&A.
- **It is one interaction.** A demo needing three steps of setup is a video.

If any of those fails, ship a recording on the slide instead. A recording that plays beats a demo that hangs.

## Sharing and metadata

Every slide gets an OG image so any single slide is forwardable. Generate them from the slide title rather than hand-designing 20 images.

Keep the deck one indexable document: canonical every slide route to the deck root and set `robots: { index: false, follow: true }` on the slides. Individual slides are thin and near-duplicate, and indexing 20 of them competes with the deck itself for the same query.

Ship the speaker notes as a markdown file in the repo, and generate a Marp version of the deck from the same `SLIDES` array when a PDF is needed: a web deck has no export button, and `output-formats.md` covers the Marp side.

## Gotchas

- Building the deck app before the outline exists. The primitives get designed around slide 3 and fight every slide after it. Story, then outline, then copy, then code.
- `h-screen` instead of `min-h-dvh`: the last line of every slide sits under the mobile browser bar.
- A demo that needs the network. It works in every rehearsal, on your wifi.
- Skipping `generateStaticParams`, so the first visit to each slide compiles live.
- One giant slides file. It grows past anything reviewable; split by section once it passes a few hundred lines.
- Indexing every slide route, which splits the deck's own search ranking across 20 thin pages.

# Writing Slides

Bold, minimal copy for speaking to, not reading from.

## Headline patterns

**Statement:** bold declarations that take a position:
- "Speed is a feature"
- "AI has no memory"
- "Passive beats active"

**Question:** create tension, invite reflection:
- "What would we do differently if we started today?"
- "So does any of this actually work?"

**Action:** drive toward outcomes:
- "Building blocks over modules"
- "Always be gardening"

**Framing:** set context for what follows:
- "How we got here"
- "The real results"

Headlines: 4-12 words, sentence case, no trailing period.

## Body text rules

- **Bold lead-in + explanation**: `**Retention is the real metric.** Acquisition gets attention, retention builds the business.`
- **Key phrase emphasis**: "We compete on **speed** and **focus**"
- **Minimal bullets**: 3-4 max on a presented deck, each earning its place (pitch decks use the denser rules in [pitch-decks.md](pitch-decks.md) instead)
- **Inline code**: `backticks` for technical terms, file names, commands

## Copy per slide type

What each type's headline and body carry. The types themselves, and what each is for, live in [outline-structure.md](outline-structure.md).

| Type | Headline | Body |
|------|----------|------|
| statement | Bold claim or insight | Optional 1-2 line explanation or stat |
| big-statement | Full-screen, maximum scale, centered | None |
| question | Provocative question | Optional context, 1 line max |
| section-divider | Section title | None |
| goals | "Goals for today" or outcome framing | 3-4 bullets, bold lead-in + brief explanation |
| data | What the data shows, never "Data" | 2-4 key numbers with labels |
| code | What this code does | 5-15 lines, syntax-highlighted, no comments |
| framework | The comparison being drawn | Matrix, do/don't, or side-by-side |
| quote | The quote itself, large | Attribution: name, role or source |
| recap | "Recap" or "Key takeaways" | One-liner per section, complete thoughts |
| resources | Grouped links | Links grouped by section |
| next-steps | Action framing | 3-4 bullets |

## Transformation examples

**Before:** "The fundamental issue with AI coding assistants is that they don't retain any context between sessions, leading to repetitive outputs"
**After:**
> **Headline:** AI has no memory
> **Subtitle:** Every session starts from zero

**Before:** "Our product strategy will be based on building reusable components"
**After:**
> **Headline:** Building blocks over modules
> **Supporting:** A platform built on configurable building blocks.

## Order of work per slide

1. Write the headline first: bold statement or question. Everything else is optional.
2. Add body only if it says something the headline does not.
3. Cut anything the speaker will say aloud anyway; a slide that repeats the talk track makes one of them redundant.