# ExplainPlan > ExplainPlan turns a plain-text script into a live, shareable, animated > presentation. The markup is the native medium of LLMs — so agents can author > decks directly. Paste Markdown, get a deck; add one line to make it beautiful. ExplainPlan is agent-first: an AI agent can discover the grammar, author a script, validate it, and inspect the result without a browser. Decks are delivered as live, embeddable presentation links — not files. ## The agent loop 1. Discover — fetch the grammar manifest below. 2. Style — pick a look for the AUDIENCE before writing (`theme:` or `bg:`/`font:`/`accent:` before the first `#`). An unstyled deck renders on the default near-black palette and gets `W_NO_THEME`. See "Pick a look" below. 3. Author — write a script (common-subset Markdown + `{…}` attribute blocks). 4. Validate — check for line-numbered errors/warnings with suggested fixes. 5. Inspect — read a render-free scene report (slides, text, duration, warnings). 6. See — render a scene to a PNG with `render_scene` to verify the REAL layout (spacing, overflow, colors, icons). Sign-in required. 7. Revise, then deliver a share/present link. ## Pick a look (do this before you write) A kids' party is not a board meeting. Match the theme to the audience — the manifest's `themeGuide` (each theme's look + who it's for), `styleGuide` (audience/mood → theme + motion + transition) and `fonts.bundled` carry this machine-readably: - Fun / hand-made (parties, celebrations, classrooms, socials) → `theme: playful` (cream, hand-lettered Caveat, six-colour palette). Add emoji to headings (`# Milo turns seven :t-rex:`), `motion: pop`, `transition: zoom`. - Loud / read from the back (posters, townhalls, launches) → `theme: poster` (saturated yellow, Dela Gothic display type). Few words, `layout: tenet` for the big lines. - Friendly but grown-up (wellness, education, onboarding, tours) → `theme: pastel`. - Cinematic / dramatic (explainers, documentaries, keynotes) → `theme: noir` + `bgAnimation: aurora` + `transition: zoom`. - Magazine / report (board updates, strategy) → `theme: editorial` + `chrome: editorial`. - Product / pitch / docs → `theme: studio` (white) or `theme: spectrum` (light grey, vivid data colours). - Dark projector / technical → `theme: midnight` — the default palette, but set it so the choice is deliberate. - Brand colours → any theme + `accent: #hex`; `{color:#hex}` on panels / donut / cards rows. Custom look → `bg:` + `font:` (any bundled font: Inter, JetBrains Mono, Caveat, Kalam, Dela Gothic One, Georgia) + `color:` + `accent:`. Themes with a palette (playful, poster, pastel, noir) colour cards, panels and donut segments automatically; `{color:name|#hex}` on a row overrides. The three `deck-*` examples in `get_examples` are complete, styled decks — adapt one rather than starting from a bare slide. ## Pictures - `![alt](url)` places an image. Images load from two places: the user's ExplainPlan library (Firebase Storage — `upload_asset`, or the editor's Assets panel) and Wikimedia Commons (`search_images`). Other hosts are blocked by the site's security policy and show as a broken image — re-host them with `upload_asset {source_url}` and use the URL it returns. `![GitHub]` places a bundled stock logo; a standalone `:name:` is an icon/emoji element. - Photo treatment on image/video lines: `{grayscale}` `{bw}` `{sepia}` `{blur}` `{vivid}` `{darken}` `{faded}` (stackable). An unsized image fills its zone (the largest it can be); `{small}`/`{medium}` or `w 300` shrink it; use `cover` for a full-bleed photo. On a `cover` photo, `scrim: bottom|top|full|none [0-1]` controls the darkening behind the text. - `search_images {query}` (no sign-in) searches Wikimedia Commons for CC-licensed photos and returns ready `![alt](url)` snippets with the licence and author — credit them in a caption or `source:` line. - `list_assets` (sign-in) lists the images/videos already in the user's ExplainPlan library (plus the stock logos) with their URLs. - `upload_asset {filename, content_type, data_base64 | source_url}` (sign-in) puts an image the human gave you into their library and returns the URL + snippet — how a picture travels from the chat into the deck. Images ≤ 10 MB (≤ 6 MB as base64 in one call; use `source_url` for larger), videos via `source_url` ≤ 30 MB. ## Grammar (machine-readable) - [Grammar manifest v3](https://explainplan.ai/grammar/v3.json): every config key, `{…}` token, theme, layout (with `bestFor`, `maxElements`, per-zone `densityBudgets`, and `defaultZone`), transition, background + animation (`bgAnimation: `), region, and 10+ canonical example scripts. `get_grammar` returns the latest; v2 stays frozen at `/grammar/v2.json`. The manifest's `defaults` object documents everything below machine-readably. ## Choosing a layout (don't default to bullets) There are 35+ layouts and most content has a better fit than a plain text/bullets slide. Match the SHAPE of your content to a layout (the manifest's `layoutGuide` and the `list_layouts` tool's `guide` carry this machine-readably; scan top to bottom, first match wins): - One bold statement/takeaway → `tenet` (or `center`; `title` for a section cover) - A pull-quote, optionally with a portrait (`![image]`) → `quote` - A few headline numbers / KPIs → `stats` - Numbered or ordered key points (label · statement · meta) → `rows` (`{rows}`; `{steps}` auto-numbers) - Parallel definitions / side-by-side comparison → `defcolumns` (plain) or `panels` (bold colored boxes) - A row of option cards with icons → `cards` - A part-to-whole / audience or market split with % → `donut` - Proportional magnitudes, then/now, or a rollout ramp → `bars` - An "X of Y" quantity → `dots` - A process/pipeline of stages (optionally a feedback loop) → `pipeline` - A growth/milestone curve over time → `timeline` - A persona/audience hero (photo + name + quote) → `persona` - A big title beside a framed content panel → `showcase` - A chat/messaging transcript (one bubble per click) → `chat` (`<` incoming, `>` outgoing; avatars are plain colour dots, so put a speaker's name at the start of the bubble: `< **Ana:** …`) - A grid/matrix of cells → `grid` (`layout: grid 2x3`, place `{r1c1}`) - Line items with amounts and a total → `ledger` (`{ledger Item | Amount}`, `{total}` on the sum row) - A trend / time series, or 2–4 metrics on one axis → `chart` (`{chart line|area|column Quarter | Revenue | Cost}` then `Q1 | $12k | $9k` per row; `{accent}` calls out a row) Set it with a scene `layout:` line, or just open the matching `{…}` region (e.g. `{donut}`, `{bars}`, `{pipeline}`) — the region sets its layout for you. When unsure, call `list_layouts` and read `guide` before writing the scene. ## Defaults & the cascade You rarely need to set things per element — set a default once and everything inherits it. - **Precedence (highest wins):** a per-element `{…}` token → the scene's config (`key: value` under its `# heading`) → the deck's config (`key: value` before the first `#`) → the built-in default. - **Deck- or scene-level keys** (set once, inherited): `bg`/`background`, `bgAnimation`, `color`, `font`, `weight`, `align`, `motion`, `speed`, `duration`, `stagger`. - **Per-scene theme:** `theme:` works under a `#` too, so a deck can change act (dark open, light middle, poster close); region slides follow the scene's theme. - **Deck-only keys:** `size`, `title`, `audio`, `volume`, `pace`, `duck`, `frame`, `chrome` (`chrome: editorial` draws a slide master on every scene). `accent: #hex` sets the accent colour (deck- or scene-level) when you don't want a theme's. - **Scene-only keys:** `layout`, `transition`, `arrow`, `notes`, `kicker`, `source` (the editorial chrome's eyebrow + footer), `heading` (`show|hide` — see below). `carry` is parsed but **experimental/not yet implemented** (no cross-scene element continuity in the render — it emits `W_CARRY_UNSUPPORTED`). - **Per-element** (inside the trailing `{…}`): entrance verb (`fly|fade|rise|pop|scale|slam|type|draw|cascade|flap|decode|none` — `cascade` = words rise in one by one, `flap` = airport split-flap board, `decode` = scramble-then-resolve; the manifest's `motion.entranceNotes` describes each), `countup` (the line's first number counts up from 0), `from `, `color`, `size`, `align`/`valign`, `wait`, `delay`, `duration`, `zone`, `bg`, `card`, `link`, `id`. - **Placement:** put a zone as a TRAILING token on each element — `Your text {col1}`. A standalone `{col1}` line or a leading `{col1}` prefix places nothing, and placement does not persist, so in a no-default-zone layout (`split`, `thirds`, `feature-grid`, `title-thirds`) every element needs its own trailing `{zone}`. Block regions (`{note}`, `{code}`, `{chat}`, `{shapes}`, `{diagram}`, `{timeline}`) are block-form only: opener on its own line, `{end}` on its own line. **Layout levers (scene keys/tokens):** `scrim: bottom|top|full|none [0-1]` on a photo cover; `bullseye: [] [
]` colours the bullseye, and `{title}` on its first line gives a straight headline instead of ring text; in `spotlight`, extra lines stay readable under the `{pinned}` word (only `{stream}` lines blur); in `easing`, lines naming curves (linear, ease-in, ease-out, ease-in-out, back, spring) pick the rows; `grid` / `feature-grid` draw framed tiles under the `#` heading. `{diagram clean}` draws crisp cards that build along the flow (node, then its arrows stretch to the next) — declare nodes as `Eyebrow | Title`, `{dark}` for the destination node. `spacing: tight|loose` scales the gap between stacked lines; `bgAnimation: aurora slow` sets background speed. Text tokens `{pullquote}` (italic pull-quote with an accent rule) and `{footnote}` (small source line pinned to the bottom edge); `{once}` on a video plays it once instead of looping. **The `#` heading — when is it visible?** The heading is always the scene's NAME (outline, remote, viewer splash). It is DRAWN as the slide title in: the region layouts (`stats`, `rows`, `bars`, `panels`, `cards`, `pipeline`, `timeline`, `ledger`, `showcase`, `title`; `donut` draws it in the ring center unless `center:` is set; `persona` draws its own name/headline instead) and every layout with a `title` zone (`bullets`, `split`, `two-column`, `columns`, `title-thirds`, `hero`) — unless you place your own `{title}` element. A photo `cover` draws it as the title over the photo (use `scrim:` to tune the darkening). It is NOT drawn in free layouts with no title zone (`center`, `tenet`, `radial`, `thirds`, `feature-grid`, `chat`): there, put the words you want seen in the body. A heading-only scene (no body) shows the heading rather than rendering blank. `heading: hide` on a scene suppresses it everywhere (chrome-free image takeovers). `scene_report` returns `headingShown` per scene. **Body lines in region scenes are never dropped:** text lines before/after a `{stats}`/`{bars}`/`{rows}`/`{cards}`/`{dots}`/`{donut}`/`{panels}`/`{pipeline}`/`{ledger}`/`{chart}` region render as a caption (under the title for stats/dots, under the content otherwise). Keep them to one or two short sentences. **Built-in defaults (override any of them):** - **Entrance: `fly` — elements slide in from the LEFT.** Change it deck-wide with `motion: fade` (etc.), per scene the same, or per element with `{pop}` + `{from top}`. `motion: none` disables animation. - **Entrance speed:** `normal` (~0.5s). Override with `speed: slow|fast|instant|0.8s`, or `{duration 0.8s}`/`{delay 0.3s}` per element. - **Theme:** none (near-black palette — and `W_NO_THEME` on a deck of 3+ scenes). Set `theme: playful|poster|pastel|noir|editorial|studio|spectrum|midnight`. - **Background:** `#0d1117`. Override `bg: #hex` or `background: `. - **Text color:** `#f0f6fc` (`color:`). **Font size:** 48px (`size:` / `{large}` / `{size 64}`). - **Transition:** none per scene (`transition: fade|slide|zoom|blur|wipe|push|cover|reveal|iris|split|shutter|fold|glitch|whip-pan|dissolve-pixel|color-sweep|parallax|merge|magic`; directional ones take `left|right|top|bottom`, e.g. `transition: push left`; add a duration or speed: `transition: zoom 1.2s`, `transition: whip-pan fast`). **Scene duration:** auto-fits content (`duration:` to pin). **Stagger:** off (`stagger: `). ## MCP endpoint (connect here) - **Remote MCP server (Streamable HTTP): `https://explainplan.ai/mcp`** — add this URL as an MCP connector in ChatGPT, Claude, or any Model Context Protocol host. No install needed. - **Two-tier model: explore anonymously, sign in to save.** - Explore (no auth): `get_grammar`, `list_themes`, `list_layouts`, `get_examples`, `validate_script`, `scene_report`, `search_images` (CC photos → `![alt](url)`). The loop: `get_grammar` → author → `validate_script` → `scene_report` → revise. - See (require sign-in): `render_scene` — render ONE scene of a script to a PNG (`scene` is 0-based; optional `width`), returned as an inline image. `render_deck` renders many (default: all, up to 16) scenes in one call at 640px — use it for the full visual QA pass. The true visual, exactly as rendered — use it to verify a layout after `scene_report`, not just read a text summary. - Save (require sign-in): `create_deck`, `update_deck`, `get_deck`, `list_decks` — persist decks to your account and get shareable `/p/` links. - Pictures (require sign-in): `list_assets` (the user's uploaded images/videos + stock logos), `upload_asset` (base64 or a source URL → stored in the user's library, returns the URL to use in `![alt](url)`). - Manage (require sign-in): `update_scene` (patch one slide, cheaper than resending the whole script), `delete_deck` / `restore_deck` (soft delete, 30-day trash), `list_revisions` + `get_deck {revision}` + `restore_revision` (append-only history). - Feedback (require sign-in): first `search_feedback {query}` to see if it's already filed (and its status/fix) — if so, `upvote_feedback {id, note?}` instead of a duplicate; otherwise `submit_feedback` — **if you can't build the layout the user asked for, don't give up: submit feedback** describing the goal. Also for bugs, confusing docs, or feature ideas. It becomes a real improvement request. - **begin_login, the reliable pattern:** show the human the short `verification_uri_complete` (or `verification_uri` + `user_code`) right away — when they arrive that way, the sign-in page shows the same code so they can see it's your request. (The long `authorize_url` still works; it just shows no code.) Then poll every `interval` seconds for the FULL `expires_in` (10 min), telling the human you're waiting; don't stop after a few tries. If it expires, call begin_login again. - **OAuth discovery:** `/.well-known/oauth-protected-resource` names the authorization server (https://login.explainplan.ai); `/.well-known/oauth-authorization-server` on this origin redirects there. 401 responses also repeat the metadata URL in the JSON error body (`data.resource_metadata`). - **Token refresh:** access tokens are short-lived (about an hour). When a save tool that worked before returns `Authentication required`, POST JSON `{"refresh_token": "…"}` to the `refresh_url` from `begin_login` for a new `access_token` — store the `refresh_token` it returns (it may rotate). Only when refresh fails, call `begin_login` again. OAuth connector clients: request the `offline_access` scope so your client can refresh on its own. - **Sign-in step-up:** a save tool called without a token returns HTTP 401 with the message `Authentication required`. Complete the OAuth flow advertised in `WWW-Authenticate`, or — in environments that cannot catch a browser redirect — call the `begin_login` tool: it returns an `authorize_url` to show the human plus a `poll_url` + `poll_secret`; poll until `status: complete` to receive an `access_token`, then send it as `Authorization: Bearer `. ## Sharing, visibility and limits (tell the human before saving) - A saved deck is viewable by **anyone who has its link** — no sign-in. Viewers see a "Make your own" button that opens the deck's **script** in the playground, so treat the script as public too. Don't put confidential material in a deck you share. - The deck appears in the owner's library (list_decks / the editor); nobody can edit it but the owner. `delete_deck` hides it from the link immediately (restorable for 30 days). - **Pricing:** free while in beta. **Limits:** script ≤ 64 KB, ≤ 60 scenes, images ≤ 10 MB (videos ≤ 30 MB), ≤ 300 files in a library, and per-IP rate limits on compute (see below). - **Account:** signing in through `begin_login` (or the OAuth connector flow) creates the human's ExplainPlan account automatically if they don't have one, so save tools work right away. Later, signing in on https://explainplan.ai with Google and the same email opens the same account and its decks. ## Validation & errors (self-repair) - `validate_script` diagnostics carry a stable `code` so you can fix without parsing prose: `W_UNKNOWN_LINE` (a `key:` line before the first `#` heading — ignored, not turned into a slide), `W_UNKNOWN_CONFIG_KEY`, `W_UNKNOWN_TOKEN` / `W_UNKNOWN_ZONE` (with `suggestion`), `W_UNKNOWN_ICON` (a `:name:` that's neither an emoji shortcode nor a Lucide icon — it would render as literal text), `W_DENSITY` (a zone/scene over its content budget — a warning, not an error), `W_UNPLACED_CONTENT` (an element with no trailing `{zone}` in a no-default-zone layout), `W_INLINE_REGION` (a `{note}`/`{code}`/… opener used inline instead of block-form), and the structural checks that used to live only in `scene_report`: Body captions under region slides sit above the editorial footer automatically. `W_NEEDS_CHROME` (a `kicker:`/`source:` line in a deck without `chrome: editorial` — it won't be drawn), `W_NO_THEME` (a 3+ scene deck with no theme/bg/font/accent — it renders near-black; pick a look for the audience), `W_EMPTY_SCENE` (the slide renders blank — add body lines or pick a layout that shows the heading), `W_OVERFLOW` (a zone's estimated content height exceeds its box — cut text or split the scene), `W_ZONE_MISMATCH` (a `{zone}` the layout doesn't have). Errors use `ERR_VALIDATION`. Warnings never block saving; errors do. - Icons/emoji: `:name:` resolves to an emoji shortcode (the full gemoji/GitHub set — see `icons.emojiShortcodes` in the manifest) first, else a Lucide icon name, else literal text (with `W_UNKNOWN_ICON`). Force a side with `:emoji:name:` / `:icon:name:`. Literal Unicode emoji always work. - Size caps (both tiers): script ≤ 64 KB, ≤ 60 scenes — over the limit is `ERR_VALIDATION`. - Tool failures return structured JSON `{ "code", "message", "hint" }` (and `diagnostics` for validation). Codes: `ERR_AUTH_REQUIRED`, `ERR_NO_IDENTITY_CLAIM`, `ERR_NOT_OWNER`, `ERR_DECK_NOT_FOUND`, `ERR_VALIDATION`, `ERR_RATE_LIMITED`. Read `hint` for the remediation. - Compute is rate-limited per IP (`validate_script`/`scene_report` ~300/hour, `render_scene` ~60/hour, `begin_login` ~10/hour); exceeding returns `ERR_RATE_LIMITED` with a `Retry-After` header. ## Human reference - [Markup reference](https://explainplan.ai/reference): the same grammar, for people. - [Playground](https://explainplan.ai/playground): no-signup live editor. ## Notes - Content is common-subset Markdown. Design is declared via `{…}` tokens, never hand-animated. Time is measured in clicks then seconds — never frames. - Features marked `unstable` in the manifest (diagram/shapes/timeline regions, character tags, spotlight) are not part of the frozen v2 contract yet, but each `unstable` region now carries a `syntax` + `example` in the manifest's `regions` — don't guess the syntax, read it there. --- # Grammar summary (v3) ## Config keys accent, align, animate, arrow, audio, background, bg, bgAnimation, bullseye, carry, chrome, color, duck, duration, font, frame, heading, height, kicker, layout, motion, notes, pace, scrim, size, source, spacing, speed, stagger, theme, title, transition, volume, weight, width Note: `key: value` lines before the first `#` set deck defaults; under a `#` they set that scene. Unknown keys warn with a did-you-mean suggestion (never silently become slide content). `bgAnimation: ` sets a background animation (deck- or scene-level); see backgrounds.animations. ## Attribute tokens ({…}) - Size: huge, l, large, m, medium, normal, s, small, xl, xxl, size — bare alias, or `size 64` - Emphasis: accent, dim, bold, light, mono, serif, sans - Editorial: pullquote, footnote — `{pullquote}` = large italic serif with an accent rule on the left (a pull-quote inside any layout); `{footnote}` = a small source/aside line pinned to the slide's bottom edge, outside the layout (alias `{fn}`). - Color: color — `color #hex` · `color $brand` · `color navy` (validated) - Motion: cascade, decode, draw, fade, flap, fly, none, pop, rise, scale, slam, type - Speed: fast, instant, normal, slow - Timing: wait, delay, duration, frames — `{wait}` / `{wait 2s}` step break; `delay 0.3s`; `duration 0.6s`; `frames 34 20` escape hatch - Direction: from, bottom, left, right, top — `from left|right|top|bottom` (for `fly`) - Loop: bounce, breathe, float, glow, pulse, shake, swing, wobble - Placement: col1…col9, r1c1, center, top, bottom, left, right — plus the active layout's named zones; unknown zone → error with suggestion - Align: align, valign — `align left|center|right` · `valign top|middle|bottom` - Media: w, width, h, height, wrap, device, volume, pan, kenburns, kb, seed, facing, thickness — device ∈ {browser|iphone|laptop}. An unsized image fills its zone (the largest it can be); `{small}` or `{medium}` shrink it, `w 300` pins a width. For a bigger photo than a zone allows, use the `cover` layout. Videos autoplay muted and loop; `{volume 0.6}` turns sound on; `{once}` plays through once and holds the last frame. - Photo treatment: grayscale, greyscale, bw, sepia, blur, vivid, darken, faded — On image/video lines; stack them (`{grayscale darken}`). bw = high-contrast black & white, faded = washed-out film, vivid = saturated, darken = dimmed for text on top. - Misc: link, arrow, id, bg, border, card ## Themes dark, editorial, midnight, noir, parchment, pastel, playful, poster, spectrum, studio ## Theme guide (name — look — best for — font) - midnight — Near-black ground, light Inter, periwinkle accent (the default palette, chosen deliberately). — Technical talks, dashboards, anything on a dark projector. — 'Inter', system-ui, sans-serif - editorial — Cream parchment, Georgia serif, burnt-orange accent — pairs with `chrome: editorial` for a slide master. — Board updates, strategy reviews, reports, anything that should read like a magazine. — 'Georgia', 'Times New Roman', serif - studio — Pure white, near-black Inter, blue accent — the clean product-demo look. — Product demos, pitch decks, docs. — 'Inter', system-ui, sans-serif - spectrum — Cool light grey, Inter, vivid blue — pairs with the named {color:…} palette on panels/donut. — Research readouts, consumer insights, data-heavy decks. — 'Inter', system-ui, sans-serif - playful — Warm cream ground, hand-lettered Caveat, a six-colour party palette. — Kids' parties, celebrations, team socials, classroom, anything that should feel hand-made and fun. — 'Caveat', cursive — palette: #ff6b35, #2ec4b6, #8a4fff, #ffbf47, #ff4d8d, #3dbb5c - poster — Saturated yellow ground, chunky Dela Gothic display type, loud primaries. — Event posters, townhalls, launches, hype decks, anything that must be read from the back of the room. — 'Dela Gothic One', 'Inter', sans-serif — palette: #ff3d00, #0b0b0b, #1f5fff, #ff2d95, #00b37e, #7a1fff - pastel — Soft lavender ground, gentle pastel palette, calm Inter. — Wellness, education, onboarding, product tours, portfolios — friendly without being childish. — 'Inter', system-ui, sans-serif — palette: #9b6dff, #5ec8d8, #ff9f80, #8fd18f, #f48fb1, #ffd36e - noir — True black, white type, a single cinematic red — pairs with bgAnimation: aurora and transition: zoom. — Explainers, documentaries, keynotes, anything cinematic or dramatic. — 'Inter', system-ui, sans-serif — palette: #e50914, #ffc107, #03a9f4, #8bc34a, #ff6f00, #b0bec5 ## Style guide (audience/mood → look) - Kids, a party, a celebration, a team social, a classroom — anything that should feel fun and hand-made → theme: playful (+ emoji in headings, `motion: pop`, `transition: zoom`) - An event poster, a townhall, a launch, a hype deck — must read from the back of the room → theme: poster (+ `motion: slam`, few words per slide, `layout: tenet` for the big lines) - Wellness, education, onboarding, a product tour, a portfolio — friendly but grown-up → theme: pastel (+ `motion: rise`, `transition: fade`) - An explainer, a documentary beat, a keynote, anything cinematic or dramatic → theme: noir (+ `bgAnimation: aurora`, `transition: zoom`, `motion: fade`) - A board update, a strategy review, a report — should read like a magazine → theme: editorial + `chrome: editorial` (kicker/source per scene) - A product demo, a pitch deck, documentation → theme: studio (white) or theme: spectrum (light grey, vivid data colours) - A technical talk, a dashboard, a dark projector → theme: midnight — the default palette, but SET IT so the choice is deliberate - A brand colour must show → any theme + `accent: #hex` (deck-level) and `{color:#hex}` on panels/donut/cards rows - A custom look → `bg: #hex|preset` + `font: 'Caveat', cursive` (any bundled font) + `color: #hex` + `accent: #hex`, all before the first `#` ## Fonts (bundled) - Inter — neutral sans — the default - JetBrains Mono — monospace — code, labels, meta - Caveat — hand-lettered marker — playful, personal - Kalam — handwriting — notes, sketches, classroom - Dela Gothic One — chunky display — posters, hype, headlines - Georgia — system serif — editorial, reports Set deck-wide with `font: 'Caveat', cursive` before the first `#`, or per scene / per element with `{serif}`/`{mono}`/`{sans}`. Any installed web/system font name also works but only these are guaranteed in rendered stills. ## Backgrounds presets: apple, charcoal, cream, dark, forest, ivory, light, midnight, navy, parchment, slate, warm, white, wine animations: aurora, bullseye, drift, none ## Layouts (name — zones — stability) - bars — zones: content — stable - bullets — zones: title, content — stable - bullseye — zones: title, media, subtitle — stable - cards — zones: content — stable - center — zones: content — stable - chart — zones: content — stable - chat — zones: conversation — stable - columns — zones: title, col1, col2, col3, col4, col5, col6 — stable - compare — zones: title, before, after — stable - cover — zones: media, content — stable - defcolumns — zones: content — stable - donut — zones: content — stable - dots — zones: content — stable - easing — zones: content — stable - feature-grid — zones: title, a, b, c, d — stable - grid — zones: r1c1 — stable - hero — zones: title, media — stable - ledger — zones: content — stable - panels — zones: content — stable - persona — zones: content — stable - pipeline — zones: content — stable - profile — zones: photo, info, links — stable - quote — zones: quote, attribution — stable - radial — zones: hub, spoke1, spoke2, spoke3, spoke4, spoke5, spoke6, spoke7, spoke8, spoke9, spoke10, spoke11, spoke12 — stable - rows — zones: content — stable - showcase — zones: title, content — stable - sidebar — zones: sidebar, content — stable - split — zones: title, col1, col2 — stable - split-left — zones: title, col1, col2 — stable - split-right — zones: title, col1, col2 — stable - spotlight — zones: content — stable - stats — zones: content — stable - tenet — zones: content — stable - thirds — zones: col1, col2, col3 — stable - timeline — zones: content — stable - title — zones: content — stable - title-fifths — zones: title, col1, col2, col3, col4, col5 — stable - title-thirds — zones: title, col1, col2, col3 — stable - top-bottom — zones: top, bottom — stable - two-column — zones: title, col1, col2 — stable ## Transitions blur, color-sweep, cover, dissolve-pixel, fade, fold, glitch, iris, magic, merge, none, parallax, push, reveal, shutter, slide, split, whip-pan, wipe, wipe-diagonal, zoom ## Motion entrances: cascade, decode, draw, fade, flap, fly, none, pop, rise, scale, slam, type speeds: fast, instant, normal, slow ## Sizes text: huge, l, large, m, medium, normal, s, small, xl, xxl media: l, large, m, medium, s, small, xl, xxl ## Emphasis breathe, glow, float, wobble, shake, swing, pulse, bounce, none ## Regions (name — stability — description) - code — stable — Code block with syntax highlighting - note — stable — Speaker notes (hidden from slides) - chat — stable — Chat transcript: `<` lines are incoming (left), `>` lines outgoing (right). At render/present time it reveals one bubble per click (a per-bubble step is added by the layout pass); scene_report models that as step-per-bubble. Each side gets a plain coloured avatar — no initials or names are inferred. There is no speaker-name syntax yet: to label speakers, start the bubble text with the name (`< **Ana:** any blockers?`). The `# heading` is not drawn on chat slides. - columns — stable — Definition columns — parallel vertical stacks, each under a top hairline. Sets the `defcolumns` layout; the scene's `# heading` becomes the title. (Distinct from the zone-based `columns` layout, which places free content in col1/col2/…) - diagram — stable — Nodes + `->` connectors; draws itself. - shapes — unstable — Geometry primitives with motion verbs. - timeline — stable — Horizontal timeline with curve easing. Labels follow the theme ink and the first/last labels anchor inward so they never clip. - stats — stable — A row of big KPI figures (value + label + sub). Sets the `stats` layout; the scene's `# heading` becomes the title. - rows — stable — An ordered/labeled row list, hairline-separated. Sets the `rows` layout; the scene's `# heading` becomes the title. Use `{steps}` to auto-number instead of writing a label column. - dots — stable — A unit/dot array ("waffle") for an X-of-Y quantity. Sets the `dots` layout; the scene's `# heading` becomes the title. SINGLE-LINE — no {end}. - cards — stable — A row of styled cards. Sets the `cards` layout; the scene's `# heading` becomes the title. Subsumes the deck's "N cards" slides (4/9/11/14/20/22). - bars — stable — A proportional horizontal bar chart (then/now stages, a rollout ramp, any X-vs-Y). Sets the `bars` layout; the scene's `# heading` becomes the title. - panels — stable — A row of boxed accent cards — a colored top bar, a pill label, a headline, body, and an optional highlighted callout. Sets the `panels` layout; the scene's `# heading` becomes the title. For challenge/objective/scope-style side-by-side framing. - donut — stable — A segmented donut sized by value, with color-matched callout cards auto-placed left/right around the ring (leader lines never cross) and big center text. Sets the `donut` layout. For a market/audience split. - persona — stable — An editorial persona/audience hero card — a diagonally-cut photo, a black corner wedge, a big white name pill with a label chip, a side pull-quote, a bordered note, and a headline. Sets the `persona` layout. The image fills the right-hand diagonal panel full-bleed (else that panel is a darker shade of the field color); the field color defaults to the deck's theme accent. Every text slot and five colours are configurable; all slots optional. - pipeline — stable — A horizontal process pipeline — a row of stages (artifact label over a dot over an owner caption), joined by a line with an entry arrow, plus an optional dotted feedback loop from the last stage back to the first. Sets the `pipeline` layout; the `# heading` is the title. Body lines after the region become the caption (first bold, rest dimmed). - chart — stable — A line, area or grouped-column chart on one y-axis — a time series or trend. Sets the `chart` layout; the `# heading` is the title. Two or more named series get a legend AND a direct label at each line's end. Body lines render as a caption. - ledger — stable — A financial table: line items with right-aligned amounts, an optional note column, hairline rules and a bold total row. Sets the `ledger` layout; the `# heading` is the title. Body lines render as a caption. ## Unstable (NOT part of the frozen v2 contract) shapes region (on the pre-launch backlog), character tags [Name], spotlight ~…~, arrow suffix -->dir, separator ___ --- # Example scripts ## Example: deck-playful-party A COMPLETE styled deck: theme: playful (cream + Caveat + party palette), emoji in headings, pop motion, zoom transitions, cards cycling the palette. Start here for anything fun. ``` title: Milo turns seven theme: playful motion: pop transition: zoom # Milo turns seven :t-rex: :birthday: layout: title A dinosaur party for 14 kids, one very excited birthday boy. Saturday, June 12 · 2–5 PM · Maplewood # The party in numbers {stats} 14 | kids invited | ages 6–8 3 | hours of chaos | 2–5 PM 1 | birthday boy | very excited {accent} {end} # Party stations :tada: {cards connector:chevron} :bone: Dig pit | Sandbox fossil hunt | 30 min :art: Craft table | Dino masks and tails | all afternoon :cake: Cake | T-rex cake, candles | 4 PM {fill accent} {end} # Who's coming {donut center:"24 guests"} Small humans | Kids | 58% | juice boxes and cake Big humans | Grown-ups | 42% | coffee and small talk {end} # Rain plan :cloud_with_rain: layout: split Sunshine {col1, accent} Backyard games {col1} Treasure hunt {col1} Indoors {col2, accent} Living-room obstacle course {col2} Dino movie + popcorn {col2} # The rule layout: tenet Every kid leaves with a balloon and a fossil. Milo's law ``` ## Example: deck-board-editorial A COMPLETE corporate deck: theme: editorial + chrome: editorial (kicker + source on every scene), stats, panels, bars with a caption, rows, a closing tenet. ``` title: Q3 Board Update theme: editorial chrome: editorial motion: rise transition: fade # Q3 board update layout: title Revenue up, burn down, one decision needed. Board meeting · November 2026 # Q3 headline numbers kicker: Results source: Finance · unaudited {stats} $2.4M | revenue | +18% YoY 78% | gross margin | +2 pts 14 | months runway | at current burn {accent} {end} # Two bets kicker: Decisions {panels} Bet 1 | Expand to Europe | London office opens January. | Needs board approval {color:blue} Bet 2 | Buy, don't build | Acquire the analytics team. | Term sheet ready {color:green} {end} # Burn multiple by quarter kicker: Efficiency {bars} Q1 | 3.2 | burn multiple Q2 | 2.6 | improving Q3 | 1.9 | best yet {accent} {end} Below 2.0 for the first time. # Decisions needed kicker: The ask {rows} Europe | Approve the London office | vote today Hire | Approve the CFO search | this month M&A | Approve the term sheet | this week {accent} {end} # The ask layout: tenet Approve the Europe expansion and the term sheet. Board ask ``` ## Example: deck-explainer-noir A COMPLETE cinematic explainer: theme: noir + bgAnimation: aurora + zoom transitions + fade motion, a quote, a timeline, stats, cards, a tenet payoff. ``` title: How GPS knows where you are theme: noir bgAnimation: aurora motion: fade transition: zoom # How GPS knows where you are :satellite: layout: title Four satellites, one clock, and a little bit of Einstein. # The system {stats} 24 | satellites | minimum constellation 20,200 km | altitude | above Earth 4 | satellites to fix | your position {accent} {end} # Einstein, inconveniently layout: quote > GPS would drift by 10 kilometres a day if relativity were ignored. Neil Ashby, GPS physicist {attribution} # The road to a fix {timeline curve:s} 1978 | First launch | Block I satellites 1995 | Full constellation | 24 birds 2000 | Selective availability off | civilian accuracy jumps 2020 | GPS III | metre-level {accent} {end} # What it enables {cards} :world_map: Maps | Turn-by-turn | everywhere :bank: Banking | Timestamped trades | to the microsecond :tractor: Farming | Tractor autopilot | centimetre rows {fill accent} {end} # The wonder layout: tenet Your phone asks the sky what time it is, four times, and triangulates you. GPS, in one line ``` ## Example: deck-townhall-poster A COMPLETE loud deck: theme: poster (yellow + Dela Gothic), slam headlines, a count-up number, cards, rows, push transitions, a tenet close. For townhalls, launches, hype. ``` title: Q4 All-Hands theme: poster motion: slam transition: push left # Q4 ALL-HANDS :loudspeaker: layout: title Thursday · 4 PM · every office + remote # We shipped layout: center 18 features {huge countup} in one quarter {l rise} # Four things to watch {cards} :mag: Hiring | 12 open roles | eng + design :shield: Security | SOC 2 audit | December :bulb: Ideas | 40 employee pitches | vote Friday :test_tube: Pricing | 3 experiments | results soon {end} # Questions we expect {rows} Hiring | Are we still hiring in Q1? | Berlin Offices | Is Lisbon opening? | remote AI | What is our AI policy? | eng {accent} {end} # The rule layout: tenet Ask the question. Someone else is wondering too. Townhall rule ``` ## Example: minimal Paste Markdown, get a deck. One slide, no directives. ``` title: Hello theme: midnight # It just works Write Markdown. - Bullets become bullets. - **Bold** stays bold. ``` ## Example: styled Add one `{…}` line to make it beautiful; `{wait}` breaks a build step. ``` # Before and after layout: split transition: zoom The old way. {col1, dim} The new way. {col2, accent, large} One more thing. {col2, wait, rise} ``` ## Example: chat A chat region reveals one bubble per click. ``` # The conversation layout: chat {chat} > Can you make me a deck? < Sure — just write it. {end} ``` ## Example: cover A section/opening cover: a hero image plus one line. ``` # Our 2026 roadmap layout: cover ![Common octopus](https://thumb.wikimedia.org/wikipedia/commons/thumb/5/5c/Octopus_vulgaris_03.jpg/1280px-Octopus_vulgaris_03.jpg) Where we're headed next. ``` ## Example: bullets A title and a short bulleted list — the default for prose. ``` # Why it works layout: bullets - Markdown in, deck out - One line to make it beautiful - Share a live link ``` ## Example: split Two columns, placed explicitly in col1/col2. ``` # Before and after layout: split The old way. {col1, dim} The new way. {col2, accent, large} ``` ## Example: thirds Three equal columns — place each in col1/col2/col3 (no default zone). ``` # Three pillars layout: thirds Fast {col1} Simple {col2} Shareable {col3} ``` ## Example: title-thirds A title over three columns. ``` # How it flows layout: title-thirds Author {col1} Validate {col2} Deliver {col3} ``` ## Example: quote A pull-quote with an attribution. The first line is the quote; a following line is the attribution — it renders on its own line with an em-dash prepended automatically (or tag it {attribution}). An optional `![image]` renders as a circular avatar to the left of the quote. ``` # In their words layout: quote > The markup is the medium. Taq Karim {attribution} ``` ## Example: feature-grid Four feature tiles (2×2) — place each in a/b/c/d (no default zone). ``` # Four features layout: feature-grid Author {a} Validate {b} Inspect {c} Deliver {d} ``` ## Example: scene-transition-bg Per-scene transition, background colour, and a background animation. ``` # Opener The setup. # The reveal transition: zoom background: #101826 bgAnimation: aurora The big idea. {large, accent} ``` ## Example: stats A KPI/stat row — big value, label, and sub, from a {stats} region. ``` # The quarter in three numbers {stats} 2.4M | monthly active users | +38% YoY 99.98% | uptime | last 90 days 4.1x | faster onboarding | since the redesign {accent} {end} ``` ## Example: rows An ordered/labeled row list — `{steps}` auto-numbers; `{rows}` uses a label column; hairline separators. ``` # Release checklist {steps} Cut the release branch | owner: release-eng Run the full test suite | ~12 min Sign off and tag | lead {accent} {end} ``` ## Example: columns Definition columns — parallel stacks (eyebrow · big headline · body · meta) under hairlines. ``` # Three plans, one platform {columns} Starter | Free | for solo makers | 1 project Team | $20/mo | for small teams | 10 projects Scale | Custom | for enterprises | unlimited {accent} {end} ``` ## Example: dots A unit/dot array ("waffle") for an X-of-Y quantity — single-line, no {end}. ``` # 500 beta testers, week one {dots total:500 filled:180 cols:40 label:"activated"} ``` ## Example: cards A row of styled cards — per-card border/fill/accent + a leading icon, chevron connectors. ``` # From idea to launch {cards connector:chevron} :bulb: Draft | shape the concept | week 1 {border:dashed} :hammer: Build | ship the MVP | week 3 {border:solid} :rocket: Launch | go to production | week 6 {fill accent} {end} ``` ## Example: editorial-chrome The editorial slide master: `chrome: editorial` + per-scene kicker/source, drawn on every scene. ``` title: Q3 Product Review chrome: editorial # The quarter in three numbers kicker: Highlights source: Product team · Q3 2026 {stats} 2.4M | monthly active users | +38% YoY 99.98% | uptime | last 90 days 4.1x | faster onboarding | since the redesign {accent} {end} ``` ## Example: bars A proportional bar chart — then/now stages, a rollout ramp, any X-vs-Y. ``` # The rollout ramp {bars} Internal | 1% | dogfood Beta | 10% Half | 50% Everyone | 100% {accent} {end} ``` ## Example: title A cover/section slide — the # heading renders big, content lines beneath. ``` # The quarter in review layout: title Q3 2026 — what shipped, what's next. Product team ``` ## Example: text-effects Text entrance effects beyond fade/rise: `slam` (lands hard), `cascade` (word by word), `flap` (airport split-flap board), `decode` (scramble, then resolve). They only read in motion — present or play the deck to see them. ``` # Departures layout: center LISBON 09:40 {flap xl} Access granted {decode l} Every word lands one at a time. {cascade l} BOARDING {slam huge accent} ``` ## Example: countup `{countup}` (alias `{count}`) makes a line's first number count up from 0 as it enters — prefixes, suffixes, decimals and thousands separators are kept. ``` # Raised this year layout: center $1,240,000 {countup huge accent} from 312 donors {l} ``` ## Example: transitions Per-scene `transition:` — 21 kinds (fade, slide, zoom, blur, wipe, push, cover, reveal, iris, split, shutter, fold, glitch, whip-pan, dissolve-pixel, color-sweep, parallax, merge, magic, none). Directional ones take left|right|top|bottom. ``` theme: midnight # One layout: center The setup. {xl} # Two layout: center transition: push left The turn. {xl} # Three layout: center transition: glitch The payoff. {xl accent} ``` ## Example: tenet One statement, stated large. The FIRST body line is the statement; the SECOND renders above it as a small uppercase eyebrow. The `#` heading is the slide's name, not drawn (with no body, the heading becomes the statement). ``` # The principle layout: tenet Nobody ever wished for more meetings. House rule ``` ## Example: donut A part-to-whole split: a segmented ring sized by value with color-matched callout cards. `label | title | value | quote` per segment; `center:"…"` sets the ring text (else the `#` heading is drawn there). ``` # Who pays for notes {donut center:"3 segments"} Students | Free tier | 55% | I just need it to work Teams | Pro | 30% | We share everything Enterprise | Custom | 15% | Compliance first {end} ``` ## Example: panels Side-by-side framing in bold boxes: `label | headline | body | callout` per panel, `{color:name|#hex}` per panel. Panels size to their content. ``` # Two ways to get there {panels} Option A | Compressed | 4 × 10-hour days, same 40 hours | Longer days hurt parents {color:blue} Option B | Reduced | 4 × 8-hour days, same pay | Cut meetings by 40% {color:green} {end} ``` ## Example: pipeline A process of named stages: `artifact | owner` per stage, `loop:"…"` adds a feedback loop from the last stage back to the first, `{muted}` greys an automated step. A sentence after the block becomes the caption. ``` # How a change ships {pipeline loop:"bug reports feed the backlog"} Commit | engineer Build | CI {muted} Review | team Deploy | release bot {end} Every stage is automated except review. ``` ## Example: chart A trend over time: `{chart line|area|column X | Series…}` then `x | value | value` per row. Values keep their unit; the last point of each line is labelled; `{accent}` calls out a row. ``` # Revenue is pulling away from cost {chart line Quarter | Revenue | Cost} Q1 | $12k | $9k Q2 | $15k | $10k Q3 | $21k | $11k {accent} Q4 | $28k | $12k {end} ``` ## Example: ledger Line items with amounts: `{ledger Header | Header}` then `label | value | note` per row; `{total}` styles the sum row, `{accent}` highlights one. ``` # Where the $400 goes {ledger Item | Cost} Cake | $120 | bakery Decor | $90 | balloons + banners Activities | $140 | crafts {accent} Food | $50 | pizza Total | $400 | {total} {end} ``` ## Example: persona An audience/persona hero card from `key | value` rows: label, name, headline, quote, note, image, plus five colour knobs — color (the main field; defaults to the theme accent), pillColor (name pill), wedgeColor (corner wedge), chipColor (label chip), nameColor (name text; auto-contrasts if unset). `image` fills the right-hand diagonal panel edge to edge (use a URL from search_images or upload_asset); without one that panel is a darker shade of color. ``` chrome: editorial # Meet the Vibes crowd source: Photo: Pfc. Trinity Carter, public domain, Wikimedia Commons {persona} label | Audience 6 name | VIBES headline | Fitness has to be fun to keep me coming back quote | If it's boring, I drag through the workout. note | Will try any new class once — and tell friends about the good ones. image | https://thumb.wikimedia.org/wikipedia/commons/thumb/7/76/Ederle_Gym_Spin_Cycle_Class_Photo_2_%286382547%29.jpg/1280px-Ederle_Gym_Spin_Cycle_Class_Photo_2_%286382547%29.jpg color | #7c5cff pillColor | #ffffff wedgeColor | #0e0e10 chipColor | #ffbf47 {end} ``` ## Example: showcase A big title on the left beside a framed content panel on the right. Body lines (and an optional image) go inside the panel. ``` # Our members look different layout: showcase Members skew social and experiential. Vibes and Feel Strongs are 2–3x overrepresented. ``` ## Example: radial Hub and spokes: the first line is the hub and the rest become spoke cards joined by connectors (or place explicitly with `{hub}` / `{spoke1}`…`{spoke12}`). Plain text or logos (`![github]`) both work; `arrow: