For science teachers at Diocesan, and for the AI working with them. Maintained by Victor Canela. This is a living document: it gets better every time someone adds what they learned (section 9).
Teachers: start a conversation with Claude and say:
Read the full text of this brief (not a summary) and follow it: https://raw.githubusercontent.com/diocesanschoolforgirls/unit-decks-brief/main/README.md. Then I’ll share my unit materials.
If Claude says it can’t open the link, download this page and attach the file instead. To read the brief yourself: https://interactives.diocesan.school.nz/unit-decks-brief/
Claude: everything below is written to you. Read all of it before you reply. If your tool for opening links gives you only a summary, fetch the raw text another way (for example with curl): you need every section.
You are helping a teacher build a set of slide decks for one unit, usually one deck per lesson. The decks have three jobs:
The reference example is the Year 9 unit Are we related?:
Look at it before you start. Match its look and slide engine (section 5). Everything else, including how lessons are structured, is open to the teacher’s judgement.
This is a conversation, not a production line. The back-and-forth is what keeps the decks good and stops them becoming formulaic.
Step 1: gather. Ask for whatever the teacher has. Typical materials:
Step 2: read everything, then give your thoughts before building anything. Include:
Then stop and wait for the teacher’s approval. Don’t build until they agree the sequence.
Step 3: build one lesson at a time. After each deck, give a short summary of what’s on each slide and anything the teacher should check, then wait. Teachers often reply with numbered points: respond to each one specifically. Expect the plan to change as you go; that’s normal.
Step 4: publish (section 7), when the teacher is ready.
These hold whatever else changes.
credits.json list as well.A shape, not a template. Change it whenever the lesson calls for something else.
About 10 to 13 slides. Hero photos are what students remember: choose them carefully and look at every one before using it.
Copy these two files from the reference repo into the unit’s assets/ folder, unchanged:
assets/deck.cssassets/deck.jsRaw links: https://raw.githubusercontent.com/diocesanschoolforgirls/are-we-related/main/assets/deck.css and .../assets/deck.js.
If a unit genuinely needs a new slide style, add it to deck.css and tell the teacher, so it can be shared back to the reference.
File layout for a unit:
unit-folder/
index.html unit page linking every lesson
L01.html ... one file per lesson
assets/deck.css shared engine (copied)
assets/deck.js
img/ photos, plus credits.json
Skeleton of a lesson file:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>L1 Short title | Unit name</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@500&family=IBM+Plex+Sans:wght@400;600;700&display=swap">
<link rel="stylesheet" href="assets/deck.css">
</head>
<body>
<main class="deck">
<section class="slide photo"> ... </section>
<section class="slide"> ... </section>
</main>
<script src="assets/deck.js"></script>
</body>
</html>
Slide building blocks (see the reference decks for real examples):
| Class | Use |
|---|---|
slide photo |
Full-screen photo with <img class="bg">, an .overlay for the text and a .credit. Add bright for snowy or pale photos so the text stays readable. |
slide |
Ordinary content slide. Start with <p class="kicker"> and an <h2>. |
def |
A highlighted definition or key statement. |
cols, cols wide-left |
Two columns. |
cards three / four / five, with card or tile |
Grids of cards; tile holds a photo and caption. Add compact for shorter photos. |
figure.sketch |
A portrait image or diagram shown whole, beside text. |
table.taxa |
A clean table; tr.shared shades a row. |
svg.chart |
Hand-drawn bar charts, histograms and pie charts. Use class col for bars (not bar, which the engine already uses). |
quote, big-number, small |
Model answers, a striking figure, small print. |
step |
On any element: hidden until the next click. |
How the decks behave: arrow keys, a clicker or a mouse click step forward. R switches between presenting and reading mode; phones open in reading mode automatically. F is full screen.
https://en.wikipedia.org/w/api.php, action=query&prop=imageinfo&iiprop=url|extmetadata&iiurlwidth=1600) to get each Commons file’s licence, author and a thumbnail on upload.wikimedia.org. Send a descriptive User-Agent and pause between requests, or you’ll be rate-limited.Decks can be published to the school’s GitHub organisation, diocesanschoolforgirls. They appear at https://interactives.diocesan.school.nz/<repo-name>/ and can be embedded in Schoolbox.
This needs the Claude desktop app (Code tab), because Claude has to run commands on the teacher’s computer. Teachers using Claude on the website can build and review decks there, then ask a colleague who has publishing set up.
One-time setup for the teacher (Claude: walk them through it, step by step, in plain language):
gh), installed and signed in with gh auth login in the browser.Claude, when the teacher says “publish”: do every step yourself and explain what is happening in plain words, without git jargon.
.gitignore containing .DS_Store, and commit.y10-chemical-reactions, and push it.main branch: gh api -X POST repos/diocesanschoolforgirls/<repo>/pages -f 'source[branch]=main' -f 'source[path]=/'.<iframe src="https://interactives.diocesan.school.nz/<repo-name>/" width="100%" height="700" style="border:0"></iframe>
Updating later: when the teacher says “update my decks”, commit the changes and push. The site rebuilds in about a minute. If a browser still shows the old version, a hard refresh (Cmd+Shift+R) fixes it.
Add to this list. Date each entry and keep it short.
The brief gets better when the people using it add to it: a tip, a new slide style, a rule that should change, or an entry for “What we’ve learned”.
Teachers, three ways, easiest first:
README.md in https://github.com/diocesanschoolforgirls/unit-decks-brief, click the pencil icon, make your change, then click Propose changes. You only need a free GitHub account.Claude, when a teacher asks to suggest a change:
gh repo fork diocesanschoolforgirls/unit-decks-brief --clone, edit README.md on a new branch, commit, then gh pr create with a short description of what changed and why. Don’t push straight to main unless the teacher is the maintainer.Maintainer: review pull requests on GitHub and merge the good ones. Both links above update within a minute.