decocms / slides

slides — presentation decks

Create and edit presentation decks as single self-contained HTML files,
rendered by Studio's <deck-viewer> runtime. The user gets a live preview
with inline editing, and exports PDF by printing (the deck ships print CSS
— one page per slide; nothing for you to generate).

Quick reference

Path convention

Decks live at /app/org/home/decks/<name>.html (<name> is lowercase kebab).
Files written there sync to Studio near-instantly and the user sees a live
preview that updates as you work.

Creating a deck

1. Read /app/org/public/core/slides/examples/deck.json once to learn the
   data shapes.

2. Author your own deck JSON (a file is easier to iterate than inline):
   { "title": …, "theme": …, "slides": [ { "template": …, "data": … } ] }

3. Render: slides-create --data @deck.json --output /app/org/home/decks/<name>.html

4. Iterate content by editing the HTML output (see lifecycle below),
   or re-render with -f only while the user hasn't touched the deck.

Themes (--theme or "theme" in data; default aurora-light):
aurora-light (clean light, soft gradients), ink-dark (dark keynote,
amber accents), bold-gradient (vivid full-bleed gradient, glass cards).

--theme also accepts a path to a custom theme file, in either shape:

1. A shell with a {{{slides}}} insertion point (copy a built-in from
   /app/org/public/core/slides/themes/ and retune its CSS custom properties).

2. A real deck ("deck-as-theme") — a complete deck whose <deck-viewer>
   holds example slides. On render, {{title}} is filled and the
   <deck-viewer> body is replaced with the generated slides. So one file is
   both an editable sample deck (open it in Studio and edit the slides inline,
   like any deck) and the generation shell — the cleanest way to author a
   brand theme.

Keep org brand themes in org-fs so they persist, e.g.:

slides-create --data @deck.json \
  --theme /app/org/home/templates/slides/brand-theme.html \
  --templates-dir /app/org/home/templates/slides \
  --output /app/org/home/decks/q3.html

Brand folders

If the org has a brand at /app/org/home/brands/<name>/ (check with
ls /app/org/home/brands/), honor it before any built-in theme (to create or
edit a brand, use the brand skill):

• tokens.css — the brand's --brand-* CSS custom properties. Inline
  them into the deck (paste into the theme <style> block; never reference the
  org-fs file by URL — preview iframes carry no cookies). A brand theme shell
  maps deck variables onto them, e.g. --deck-accent: var(--brand-primary);.

• slides-theme.html — if present it's a ready deck shell for this brand;
  pass it as --theme /app/org/home/brands/<name>/slides-theme.html.

• brand.md — voice, tone, do's and don'ts; read it and follow it when
  writing slide copy.

• logo.* — the brand logo; place it on the title/closing slides.

Slide templates and their data

This skill is built on the templating skill
(/app/org/public/core/templating/SKILL.md). For a one-off custom slide
or deck template, render it directly with create-from-template; for an
org's own slide layouts, keep them in /app/org/home/templates/slides/ and
pass --templates-dir — they resolve before the built-ins.

Lifecycle — templates create, edits go to the HTML

Rendering is for creation. After that, the HTML file is the live
artifact: the user can edit it inline in the preview (retype text,
reorder/duplicate/delete/skip slides) and those edits are saved back into
the same file. Therefore:

• Always re-read the deck file before editing it — your last copy may
  be stale.

• Iterate with read/edit on the HTML, not by re-rendering;
  slides-create -f overwrites the user's edits.

Editing slides by hand

Slides are the direct <section> children of <deck-viewer>. Rules:

• Fixed 1920×1080 canvas (the runtime scales it). Never set
  position/inset/width/height on the <section> itself; lay out
  inner elements freely.

• Static HTML only — no JS-rendered text, no per-deck scripts. Inline
  editing depends on the text being in the markup.

• Reuse the theme's classes (deck-h1, deck-h2, deck-sub,
  deck-body, bullets, cols, card, kpi-value, …) and tune the
  look via the CSS custom properties in the theme <style> block rather
  than scattering literal colors.

• Entrance animations: gate on section[data-deck-active], keep the
  visible end state as the base state, respect
  prefers-reduced-motion — required so print/PDF renders full content.

• Images: absolute public URLs or data URIs only (relative paths do not
  resolve when the deck is served). Prefer CSS shapes/gradients.

• Content budget: a slide fits roughly one heading plus 5 bullets (or
  3 cards). When in doubt, split into two slides.

• data-deck-skip on a <section> hides it from presentation and print
  without deleting it.

• Never touch the <script src="/deck-runtime/v1/deck-viewer.js"> tag or
  rename <deck-viewer>.