Slides & decks

Slides: one heading, one slide

Any doc renders as a deck with chiltepin slides. Each # or ## heading starts a new slide and becomes its title. Everything until the next heading — prose and blocks — stays on that slide. (### and deeper stay in the slide body.)

# Why now
A sentence of context, then any blocks under this heading.

```drivers
items:
  - { title: Slow, body: "p95 hit 2.4s.", icon: clock, accent: amber }
```

# The fix
Next heading → next slide.

A normal doc already presents cleanly. To write for slides, keep each heading to one idea: a title plus one strong visual reads better than dense prose.

Layout

Slides lay themselves out: light slides center, full slides top-align, and a slide with substantial prose plus a diagram automatically goes side by side — message left, exhibit right. Diagrams render borderless on the stage, without the card frame pages use.

The text a deck needs

Three things a stage handles differently from a page:

• The action title gets a supporting line. A block's lede pins under the slide title at a fixed size — the sentence that turns a title into an argument, immune to the fitter that scales the exhibit.
• Provenance goes in the footer. {source: …} on the heading lands beside the deck title and page number, where every consulting exhibit carries it. Under the block it would shrink with the exhibit.
• Body copy runs at presentation size — 19px prose, 17.5px list items, 19.5px in a {split} message column — with the measure still capped, because long lines are harder to follow on a screen, not easier.

A deck with two or more divider bands also grows a tracker in the slide header: the parts of the deck with the current one lit, so the room always knows where it is.

Blocks are re-laid-out for the stage, not shrunk onto it: tables and card layouts take the full slide width with presentation-size type, stacked cards (slo, okr, stories, envelope, trace) turn into a row across the stage, and every small label — chips, captions, eyebrows — sits at a readable floor rather than the size a printed page wants.

Four markers on a heading override the automatics (they're stripped from the displayed title):

Good to know

• The meta block becomes the cover slide. Every other slide gets a footer with the deck title and page number.
• Long sections split automatically across slides, keeping their title.
• chiltepin build renders both views of every doc — the page and a deck — linked by a Doc | Slides toggle. No extra command.

Presentation-style decks

For an executive deck, give every slide the same shape: a claim, one exhibit, a takeaway.

• Write titles as sentences. "Checkout latency is costing us conversions" — the slide then proves it, and the block's lede becomes the supporting line under it.
• Open with scqa — situation, complication, question, answer. The executive summary in the order that argues.
• Compare options with harvey — Harvey balls beat a table of numbers in front of a steering committee, and the weighted footer is computed.
• Defend the plan with scenarios — base, upside and downside against the same drivers.
• Use {split}. Short prose left, exactly one block right. The block is the evidence.
• Open each part with a divider block — a clean full-width break.
• Give the key metric its own slide with a bignumber block.
• Close with takeaways — the 2–4 things the room should remember.
• Walk a process with chevrons — a phase strip with the current phase lit — and plan with roadmap — themes by period with status chips and a now rule.

Need the deck as a file? chiltepin slides docs/plan.md -o deck.html writes one self-contained HTML file; chiltepin pdf prints it.

Diagrams build as you advance

A diagram with a natural order reveals one item at a time before the deck moves on. sequence follows its messages (and its alt / else frame markers), flow walks the graph from start, saga runs its steps and then its compensations, spans arrives bar by bar; state, steps, timeline and rollout follow document order.

→ / Space / PageDown reveal the next step, then advance the slide. ← walks back. The step just revealed takes the accent for that moment — the one presentation-time exception to the one-accent rule.

Nothing is hidden by the markup: without JavaScript, in print, and on the page, the diagram is whole. Each build is announced through an aria-live region ("Step 3 of 18"), and prefers-reduced-motion drops the fade.

Opt one slide out with a heading marker:

## Architecture at a glance {nobuild}

One look, no themes

Chiltepin has a single visual design — dark by default, with one accent the renderer places on the one focal thing in each diagram. The only choice is colorScheme in chiltepin.config.json: dark, light, or system (the reader's OS chooses). It applies to decks and exported HTML alike; print and PDF are always light.

There is nothing else to pick. There are no themes, no presets and no palette; a leftover theme key from an older version is ignored.

That is a deliberate trade. Meaning in a Chiltepin diagram travels through shape, stroke weight, dash and typographic chips, and colour is spent on exactly one thing per figure, chosen from the data. A swappable palette breaks that rule — and with it the guarantee that every diagram in a repository reads the same way. The full specification is packages/render/DESIGN.md.