Skip to content
Back to search

deck-kit

SkillWorks with Claude CodeGitHub

Build a polished static presentation from a single data file — design first, then website. Use when someone says "/deck-kit", "make a presentation/slide deck/pitch", "build a deck for X", or wants a talk they can run in the browser and deploy to their own server. Produces slides from deck/slides.json with an overview, phone reading mode, PDF export and a second presenter-notes window.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bonesisis--deck-kit/badge.svg)](/listings/bonesisis--deck-kit)

HTML

<a href="/listings/bonesisis--deck-kit"><img src="/api/listings/bonesisis--deck-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/<you>/deck-kit
cd deck-kit

python3 deck/build.py                     # slides.json -> deck/index.html
(cd deck && python3 -m http.server 4321)  # then open http://127.0.0.1:4321/

Edit `deck/slides.json`, rebuild, reload. That's the loop.

**Keys:** arrows / space move · **O** overview · **F** fullscreen · **B** blackout · **H** help · **N** notes window.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 133 lines
  1. ---
  2. name: deck-kit
  3. description: Build a polished static presentation from a single data file — design first, then website. Use when someone says "/deck-kit", "make a presentation/slide deck/pitch", "build a deck for X", or wants a talk they can run in the browser and deploy to their own server. Produces slides from deck/slides.json with an overview, phone reading mode, PDF export and a second presenter-notes window.
  4. ---
  5. # Deck Kit
  6. Turn a topic into a static presentation: one data file, a few layouts, and a
  7. browser engine that already does navigation, an overview, a phone reading mode,
  8. a PDF export, and a **second notes window** that stays in sync with the deck.
  9. The order is deliberate: **design first, website second.** Agree the look
  10. (colours, type, feel) before pouring in content, because the look lives in one
  11. tokens file and everything else derives from it.
  12. ## When to use this
  13. Someone wants a talk, pitch, or lecture they can present in the browser and host
  14. themselves — not a Google Slides / PowerPoint file. If they want a `.pptx`, this
  15. is the wrong tool.
  16. ## What's in the repo
  17. ```
  18. deck/
  19. slides.json all content (you edit this)
  20. design/tokens.css the design handoff: colours, fonts, spacing
  21. css/deck.css layout + transitions
  22. css/notes.css the notes window
  23. js/deck.js the engine (don't fork it per deck)
  24. build.py slides.json -> index.html (stdlib only)
  25. deploy/ nginx + compose for an Ubuntu server
  26. tools/smoke.mjs headless checks
  27. ```
  28. ## Workflow
  29. ### 1 · Design (do this first)
  30. Settle the look before the content. Ask, or decide from the topic:
  31. - **Mood** — calm/editorial, bold/loud, technical/plain?
  32. - **One accent colour**, plus a background: light (`--paper`) or dark
  33. (`--night`). A slide opts into dark with `"theme": "night"`.
  34. - **Type** — the kit ships system fonts (no download, no licence). Point
  35. `--font-serif` at a licensed face only if asked.
  36. Then edit **`deck/design/tokens.css`** — only the raw values under "Brand". This
  37. one file is the whole design system; don't scatter colours into other CSS.
  38. Show the user one slide rendered in the new palette before writing all the
  39. content. That rendered slide *is* the design sign-off.
  40. ### 2 · Build the content
  41. Put everything in **`deck/slides.json`**. One object per slide; pick a `layout`:
  42. | layout | fields |
  43. |-------------|--------|
  44. | `title` | kicker, title, statement, lead |
  45. | `statement` | kicker, title, statement, lead |
  46. | `bullets` | kicker, title, items[] |
  47. | `split` | kicker, title, left{head,items[]}, right{head,items[]} |
  48. | `metric` | kicker, title, metrics[{value,label}], lead |
  49. | `closing` | kicker, title, statement, lead |
  50. Every slide may also carry:
  51. - `"kicker": "Topic · Speaker"` — the part after `·` shows as the speaker chip.
  52. - `"notes": [...]` — speaker notes for the second window. Prefix a line with
  53. `## ` for a heading, `- ` for a sub-point, `[like this]` for a stage cue.
  54. Wrap a number in `**bold**` to make it jump out.
  55. - `"soll": "1:40"` — the target time for this slide's section; the notes clock
  56. shows `0:48 / 1:40` and turns the accent colour when you run over.
  57. Text is HTML-escaped at build time: write `<`, `&`, `"` as themselves. To add a
  58. layout, add one `lay_*` function in `build.py` and a few CSS rules — don't hand-
  59. write HTML into slides.json.
  60. Then:
  61. ```bash
  62. python3 deck/build.py # writes deck/index.html
  63. ```
  64. ### 3 · Verify
  65. Serve it (not `file://`) and open it:
  66. ```bash
  67. (cd deck && python3 -m http.server 4321 &)
  68. open http://127.0.0.1:4321/ # or xdg-open on Linux
  69. node tools/smoke.mjs # headless checks
  70. ```
  71. Keys: arrows/space move, **O** overview, **F** fullscreen, **B** blackout,
  72. **H** help, **N** notes window. The notes window also prints every slide's notes
  73. at `…/index.html?notes&all`.
  74. ### 4 · Deploy
  75. See `deploy/DEPLOY.md`. In short: build, copy `deck/` to the server as
  76. `deploy/site/`, `docker compose up -d`. During the talk, extend (don't mirror)
  77. to the projector, **F** on the projector, **N** opens the notes window for your
  78. laptop.
  79. ## Lessons baked in — don't relearn them the hard way
  80. - **A CSS-only change still needs a rebuild.** The CSS/JS links carry a content
  81. hash (`?v=…`), so without re-running `build.py` a cached browser keeps the old
  82. file. This is the single most common "my change didn't show up".
  83. - **The hash is output-only.** The engine writes `#3` to the URL but only reads
  84. it once, at load. There is no `hashchange` listener. When you test, load each
  85. slide fresh (`index.html#3` as a full navigation with a changing query), don't
  86. hash-jump inside one page — nothing will move.
  87. - **Never add an SPA fallback** (`try_files … /index.html`). A missing file must
  88. 404. With a fallback, one dropped mount makes every path serve index.html and
  89. the deck looks replaced.
  90. - **Notes live in a `<template>`.** A `<template>` is never rendered, so notes
  91. never leak onto the projected slide or into the PDF. Keep them there.
  92. - **The notes window couples by BroadcastChannel.** Same browser, same device,
  93. same http origin only. It does not cross devices and does not work under
  94. `file://`. An iPad on the same tailnet still won't couple — give it the
  95. `?notes&all` print page instead.
  96. - **Don't set `html, body { overflow: hidden }` on the notes window.** The deck
  97. needs it (a deck doesn't scroll); the notes print view must scroll, and the
  98. live notes window is a fixed frame where only the middle scrolls.
  99. ## Privacy when publishing
  100. If you push a deck built from this kit to a public repo, scrub real content and
  101. infrastructure first: hostnames, IPs, tailnet names, usernames, SSH key paths,
  102. and the commit author email (set a repo-local GitHub noreply address). Keep
  103. `.env`, `htpasswd` and real `deploy/site/` content out of git — the shipped
  104. `.gitignore` already does.
README.md · README · 80 lines
  1. # Deck Kit
  2. Build a polished **static presentation** from a single data file. Design the
  3. look first, then pour in the content. No framework, no build tool, no
  4. dependencies — just Python's standard library and a browser.
  5. The engine already does the tedious parts: slide navigation, an overview grid, a
  6. phone reading mode, a PDF export, and a **second presenter-notes window** that
  7. stays in sync with the deck and carries a clock.
  8. > Replace the example deck with your own. The example is neutral on purpose.
  9. ## Why
  10. Presentations are usually locked in a desktop app or a cloud account. This keeps
  11. one as plain files you own: edit `deck/slides.json`, run one command, open the
  12. result, host it on your own server. Because it's static, it loads instantly,
  13. works offline, and deploys anywhere.
  14. ## Quickstart
  15. ```bash
  16. git clone https://github.com/<you>/deck-kit
  17. cd deck-kit
  18. python3 deck/build.py # slides.json -> deck/index.html
  19. (cd deck && python3 -m http.server 4321) # then open http://127.0.0.1:4321/
  20. ```
  21. Edit `deck/slides.json`, rebuild, reload. That's the loop.
  22. **Keys:** arrows / space move · **O** overview · **F** fullscreen · **B**
  23. blackout · **H** help · **N** notes window.
  24. ## The two steps
  25. 1. **Design** — set one accent colour, a light or dark background, and the type
  26. in **`deck/design/tokens.css`**. That one file is the whole design system.
  27. 2. **Build** — write slides in **`deck/slides.json`**, pick a `layout` per slide
  28. (`title`, `statement`, `bullets`, `split`, `metric`, `closing`), add speaker
  29. `notes` and a target time `soll`. Run `python3 deck/build.py`.
  30. Full guidance — including the presenter notes format and the design handoff — is
  31. in [`SKILL.md`](SKILL.md). If you use Claude Code, drop this repo in and the
  32. skill drives the whole design → build → verify → deploy flow for you.
  33. ## Prerequisites
  34. - **Python 3** to build (standard library only — nothing to install).
  35. - A browser to present.
  36. - To host it: an **Ubuntu server with Docker**, optionally
  37. [Tailscale](https://tailscale.com) to keep it private. See
  38. [`deploy/DEPLOY.md`](deploy/DEPLOY.md).
  39. - Optional: **Node 18+** for the headless checks in `tools/smoke.mjs`.
  40. ## What's inside
  41. ```
  42. deck/
  43. slides.json all content — the file you edit
  44. design/tokens.css design handoff: colours, fonts, spacing, motion
  45. css/deck.css layout, transitions, overview, help
  46. css/notes.css the second notes window
  47. js/deck.js the engine (shared; don't fork per deck)
  48. build.py generator, standard library only
  49. deploy/ nginx config + docker compose for an Ubuntu server
  50. tools/smoke.mjs headless smoke test
  51. SKILL.md the full workflow (and a Claude Code skill)
  52. ```
  53. ## Presenting on two screens
  54. Extend (don't mirror) your laptop to the projector, open the deck, press **F**
  55. on the projector and **N** to open the notes window on your laptop. Both windows
  56. move together. This needs both windows served from the **same http address** —
  57. a double-clicked file won't couple. Printable notes: `…/index.html?notes&all`.
  58. ## License
  59. MIT — see [`LICENSE`](LICENSE). Use it, change it, ship your own decks with it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.