kevin-aoun/deckify

Slide decks

A deck is one HTML file + a sibling assets/ folder + a logo/ folder: a fixed 1280×720 #stage, slides as <section class="slide"> (one .active at a time), with three linked, never inlined files in assets/:

• theme.css — colors + fonts only; the one file to edit to restyle a deck.
• deck.css — structure, type scale, spacing, every layout rule. Rarely touched.
• deck.js — navigation, scaling, presenter notes, theme toggle.

The logo is logo/logo.svg, not baked into a stylesheet. Linking (not base64-ing) assets keeps one source of truth and the file ~25× smaller.

→ Full tokens, type scale, spacing, palette, and visual + voice rules live in reference/design-system.md. Read it before touching structure.

Three rules every content slide follows

These are what make a deck read as designed, not dumped. Check them first.

1. Concept + concrete example — always both. Name the idea in plain language (a title plus a 1–2 sentence "what it is / when it matters", readable by a non-expert) and show one concrete example (a before/after, a real snippet, one number, a diagram). A lone example reads as "dropped in from nowhere"; a lone concept reads as a doc page.

2. Layout diversity — fit the layout to the content, and vary it. Each slide picks the layout that best carries its example, not whatever the previous slide used. Never repeat a layout on adjacent slides, and don't let any one layout (especially the two-card .cmp) carry more than ~3–4 slides across the deck. Name a layout per slide in the outline so the variety is visible before you build.

3. Write from experience, not from documentation. Every slide should sound like a veteran who has used the thing for years explaining it to a colleague: simple, because deep understanding compresses, and loaded with the non-obvious — the defaults that bite, the gotcha that costs an afternoon, the one command nobody tells you about, the real numbers and limits. Before writing a slide, ask: "what would the person who has run this in production for five years say here?" If a sentence could appear in a brochure or restates the docs' first paragraph, cut it and replace it with something only experience teaches. Marketing copy is a build failure, not a style choice.

→ Which layout for which slide, the full lookup, and anti-patterns: reference/choosing-a-layout.md. Live thumbnails of every layout: catalog.html.

Interactive by default, PDF on request

Decks are HTML-first: they are presented and shared as the HTML file, so use the medium. Do not design down to a static PDF — render a PDF only when the user explicitly asks for one (and then everything must survive print; see below).

• Fragments (progressive reveal): add class frag to any element and deck.js reveals fragments one arrow-press / click at a time before advancing to the next slide; stepping back hides them in reverse. Use them where the order of appearance teaches — a follow-along command then its output, steps of a demo, a punchline after its setup. Don't fragment decoration.
• Small animations: the .frag transition (fade + 8px rise) is the house motion. Keep any extra motion subtle, CSS-only, and purposeful; no looping distractions.
• Print safety is non-negotiable: @media print reveals all fragments automatically, so anything interactive must read correctly with everything shown at once. Never hide content behind hover-only or JS-only states that print can't reach.
• Hands-on / workshop decks: when the deck teaches a tool, prefer a follow-along track — exact commands, expected output, and "now break it" steps the audience can run live — over narrated claims. Fragments pace the follow-along.

Workflow — content first, then slides

Show, don't tell. Never jump straight to HTML — the narrative is written and approved as a .md first.

1. Understand. Read the source and draft the argument plus the concrete examples each point will show. If the material is thin on specifics, gather them (or ask).
2. Ask. Come back with informed questions before writing — audience, thesis, which examples to feature, length, theme (dark/light/both), branding (palette + logo).
3. Draft the .md. Write the narrative as <deck>-outline.md: one section per slide — kicker, title, the concrete example it will show, and its layout.
4. Confirm — get all three signed off before building any HTML: (a) content (the outline); (b) palette — state default or custom; if custom show the accent
   • key hex, deriving from a brand/screenshot per reference/theming.md; (c) layout per slide with one line of why each fits, so rule 2's variety is visible. Also settle the logo (logo/logo.svg, or the neutral placeholder).
5. Build. Scaffold from assets/deck-scaffold.html, then add each slide by copying the matching <section> from assets/templates/<layout>.html and editing the copy (styling lives in deck.css, so the classes just work). Full new-deck and per-slide steps: reference/choosing-a-layout.md. Keep the standardized header; never add inline font-size/margin; never use em dashes (—) in any copy.
6. Verify → export. Screenshot or print every slide and look for overflow and layout monotony before claiming done; on slides with fragments, check both the initial and fully-revealed states. Export a PDF only when the user asks, with assets/export-pdf.sh — see reference/export.md.

When to ask the user (don't guess these)

• Before drafting (step 2): topic, audience, thesis, which examples, length, theme, palette + logo.
• At step 4: content and palette and the per-slide layout plan — all approved before any HTML.
• Theme of the deliverable / PDF (dark vs light vs both).
• Palette: default or custom (accept hex, a brand name, or a screenshot to derive from — confirm before applying).
• Images: decks need real screenshots/diagrams — ask the user to supply them; use the hatched .imgph placeholder only as a stand-in, and flag it.
• Density: if a title or content won't fit, ask whether to trim copy or accept compact — don't silently shrink fonts off-scale.

The header (the one structural non-negotiable)

Every slide uses the standardized header — .tagrow (kicker + brand) then .shead (.headline + optional .sub), in that order. Set class="shead" (or shead compact for dense data/diagram slides) and let the tokens set every size and gap; do not hand-tune font-size or margin per slide. The full three-level hierarchy and its token table are in reference/design-system.md.

Files in this skill (where to look for what)

• catalog.html — visual gallery of every layout (self-contained; open to pick). Rebuild with scripts/build-catalog.py.
• reference/choosing-a-layout.md — which layout for which slide: decision guide, full lookup table, anti-patterns, build-from-template steps.
• reference/design-system.md — tokens, palette, type scale, spacing, visual + voice rules.
• reference/theming.md — recolor / apply a brand palette (edit theme.css; derive from a brand or screenshot).
• reference/slide-types.md — copy-paste HTML for the layouts without a dedicated template file.
• reference/export.md — verify + one-command PDF export.
• assets/theme.css — colors + fonts (edit to restyle). assets/deck.css — structure/layout + .frag reveal + @media print. assets/deck.js — nav/scaling/notes/theme + fragment stepping.
• assets/templates/*.html — one previewable, copy-and-modify slide per core layout.
• assets/deck-scaffold.html — new-deck starter. assets/export-pdf.sh — one-command PDF export.
• assets/render.js + scripts/combine.py — fallback screenshot→PDF pipeline (needs npm; only if print fails).
• scripts/build-catalog.py — regenerates the self-contained catalog.html.
• assets/logo/logo-placeholder.svg, assets/logo/hero-bg.svg — placeholder logo + hero background.