Decklet

decklet — agent authoring skill

You produce a model (JSON). The toolchain produces a deck (one .html file) that a human can drag, retype, present and print. Your job is to get the model right; the validator and verifier tell you when you haven't.

content + format + style  →  slide plan  →  model.json  →  validate  →  create  →  verify  →  hand-off

All commands run from the repo root with plain Node ≥ 22. Installed as a Claude Code plugin, the repo root is ${CLAUDE_PLUGIN_ROOT}; installed with npx skills add, it is the skill's own directory. Only verify (and import-html) need the optional playwright devDependency.

INPUTS

1. Content — anything

Outline, markdown, meeting notes, a transcript, a spreadsheet, a brief. You distil it; nothing is pasted verbatim. One idea per slide. Numbers become Stat rows, lists become 2–4 short Body rows or tiles, sequences become boxes with arrows, comparisons become two columns.

2. Format — one of

Experimental means: canvas sizing, editing, contact sheet and PDF all work; text does not flow across pages — every page is a slide you lay out yourself, and a document longer than its page is your problem to split. Treat a document as N fixed pages.

3. Style — a style guide, an inferred brand, or the neutral fallback

style.json = {tokens, roles, pad} (STYLE CONTRACT below). Obtain it in this order:

1. Style guide / brand file given → map its palette to tokens, its type scale to the eight roles. Fonts must be installed on the viewer's machine or be system stacks — the deck loads no webfonts. Put the brand font first, a system fallback after.
2. URL or screenshots given → infer: background, ink, muted ink, one accent, a card surface, a hairline. Headline family (serif/sans/mono), body family. Build tokens + roles from that. Say in the hand-off what you inferred.
3. Nothing given → omit --style; the template's neutral dark scale is used.

Sizes in roles are in model pixels for the chosen canvas. Rough scale factors: 960-wide ×1, 1600-wide ×1.67, 1080 carousel ×1.9 (viewed small), 816 document ×0.75.

PROCESS

Step 1 — slide plan (write it down before any JSON)

For each slide: name · layout · supertitle · title · body elements (kind + count). Cap: ~60 words of Body per 16:9 slide, 3–4 tiles per row, 5 bars per chart, 4 boxes per flow. A content-slide title is one line at H1; a cover or closing headline uses Title (the display size), two lines at most.

Step 2 — model rows

Discipline, in order of importance:

• Role discipline. Every text row has a role (or a slot whose layout slot has one). A row never sets font, size, lh, ls or mono — the validator rejects it. Rows may set weight, color, tt, italic, align.
• Slot discipline. Supertitle and title geometry lives in layouts.<name>; the slide row is {slot:'title', text:'…'} with no x/y/w. Define one layout per slide family (title, content; add section, two-col as needed).
• Master discipline. Anything that appears on every slide (footer, rule, mark) is a master row, once — chrome is deck-wide and never varies per layout. Exactly one master row has footer:1; the engine renders the page counter inside it, with its right edge on styles.margin. Never type 3 / 9 into a row.
• Text-fit. A label that must stay on one line gets nowrap:1 and enough w (≈ cw × size × chars — the role's measured glyph width, 0.46 for the neutral sans, 0.69 for the mono Label), or w:'auto' to hug. Chips/pills: w:'auto' + p:'chip' (+ bg/bd/radius); one that sits on a right edge takes right: instead of x. Body copy gets a w that yields ≤ 3 lines at the role's size.
• Charts are rows. A bar or line chart is one chart row (CHART ROW below) that create expands into bars, lines, dots and Label rows with the drawing rules applied — write the data, not the geometry. By hand, the same shape: bars {x,y,w,h,bg,bar:1} bottom-aligned on a baseline line; value labels as Label rows above, axis labels below. Donut: {x,y,w,donut:72} + a Stat row centred on it. Tiles: {x,y,w,h,tile:1,role:'Stat',text} + a Label row beneath.
• Cards are groups. There is no container row: a card is a tile plus its rows sharing one group — {x,y,w,h,bg,bd,radius,group:'card1'} and each text row inside it with group:'card1', every row at its own canvas x/y. The human drags the card and the rows come along; you still position each row, once.
• Colour. Use var(--accent), var(--fg), var(--muted), var(--line), var(--card) so a style swap re-themes the deck; literal hex only for chart series.

Step 3 — validate (no browser)

node bin/validate.mjs model.json --style style.json            # 0 errors required; read every warning
node bin/validate.mjs model.json --style style.json --strict   # warnings fail too — use before hand-off

Always pass the same --style you will pass to create. Text fit is only meaningful against the scale the deck will actually wear: without it the model is measured against the template's neutral roles, so validate can report 0 warnings on a model create --style then floods with overflow — and verify fails on. Omit --style only when there is none.

Step 4 — create

node bin/create.mjs --model model.json [--style style.json] --out deck.html --format slides [--space 1600x900] [--title "…"] [--from prev.html]

Refuses an invalid model (--force to override while iterating). Stamps deck.id (born once, from the first model — the browser's storage namespace, stable across versions), deck.rev (this build's content hash), a slide.id on every slide and a row id on every row that has none — deterministic (s1, s2… / r1, r2…), so the same model builds byte-identically.

Revising a deck a human has touched — --from is mandatory. The deck file carries the human's edits (/*LOG*/) and its version history (/*VERSIONS*/). Run, in this order:

node bin/edits.mjs deck.html                       # 1. READ what the human changed — before you touch the model
node bin/create.mjs --model model.json --out deck.html --from deck.html   # 2. write the new version LAST
node bin/verify.mjs deck.html                      # 3. verify the result

--from inherits the deck id and the slide/row ids (by content, then by position — carry ids in model.json to make it exact), replays every logged edit onto the new model (human wins; a key you also changed is reported as a conflict and the human's value stays — put yours in the log's conflict if it matters), and pushes the file's previous state into the version history, so nothing the human did can be lost by a rebuild. The diff-and-migrate is the last thing you do, never the first: read the log, keep their geometry and text, then regenerate.

The deck names itself. --title wins, else the model's own title, else decklet; the winner is written into the model and the runtime titles the document from it. One short, human name — you are the one who writes it — becomes the browser tab, the ⤓ PDF filename and the ⌘S save-a-copy filename.

Step 5 — verify (mandatory)

node bin/verify.mjs deck.html [--refs shots/] [--out verify-out/] [--threshold 0.5] [--strict]

• Contract — always.
• Air — always, in validate, with no browser: every row's declared box owes its neighbours styles.gap (default 4px). Two boxes closer than that, or overlapping, fail the contract unless one is wholly inside a painted box (containment), they share a group, or one says over:1. A text row with no h is estimated from its line count and a w:'auto' row from cw × chars — a collision resting on an estimate is a ~ warning, not an error. This is the gate that refuses the layout before it exists; parity below measures what actually rendered.
• Layout parity — always (needs Playwright): no text row overflows its box, every nowrap row renders one line, imported rows render their source line count, every element is inside the canvas, no painted row is drawn through a text row, zero page errors. Five shapes — four measured on real geometry (glyph rects and sampled strokes, never bounding boxes), the fifth asked of the compositor:
  1. ink through text — a line, curve or rule crossing a label's glyphs;
  2. text straddling a container — a label crossing a box/tile border, or hanging half out of the box meant to hold it;
  3. an arrow head inside a fill — a connector aimed at a target's centre instead of stopped on its edge (fix with to:);
  4. text over text — a title landing on a caption;
  5. text under paint (occlusion) — a text row hidden by an opaque row painted later in els (a tinted box, an image, a bar). The compositor is asked, not the geometry: elementFromPoint at five samples per line rect. Reported as slide 2: row 3 (Label 'kicker') under row 9 (box) — reorder els (paint first) or move the box. It fails like the other four; a hidden row is never a warning. Containment is not collision: text on a tile, a label inside a box, a slide backdrop all pass. A tint with no border is a backdrop and a circle/pill outline is decoration — neither is a container edge. A headless stroke crossing a card is routing, not a landing. over:1 opts a row out of all five.
• AE pixel diff — when --refs exists (needs ImageMagick): < 0.5% of pixels differ at 2% fuzz. AE alone passes wrapped labels; parity is what catches them — that is why parity is not optional.

Fix the model, not the output. Re-run until VERIFY PASS. Attach verify-out/results.json to your report.

Step 6 — hand-off notes for the human editor

Say, in this order:

1. Where the file is and that it opens from disk in any browser, no install, no network.
2. HUD (the full set, left to right), four groups after the spacer, a hairline between groups; every control names itself and its key on hover (data-tip, instant — never the OS title delay): prev / next (chevrons; ← →) · save state: versions (history icon wearing the autosave dot as a badge: green = the file has everything · amber = saved in this browser, N edits not in the file yet · red = nothing persists; click opens the versions menu, whose first row is Save ⌘S · pin · restore) · edit: + (Text / Box / Slide) · duplicate (copy-plus icon: the selected rows, offset 16px, the copies become the selection · else the slide, after itself · in the sheet, the selected slides) · grid + guides + snap (grip icon; G; off by default, dims when off: a 16px dot grid over the slide and this slide's layout lines — slot edges, the content margin, the canvas mid-lines — of which only the line being held shows; a drag, a resize or a connector nib snaps to a line within 10px, else to the grid; a circle snaps by its centre; a connector end also snaps to the eight 45° rays out of its other end; never in present, print, the sheet, the PDF or the saved file) · spellcheck (spell-check icon; on by default, dims when off: the words the build's dictionary refused — nspell + dictionary-en at create, optional — are underlined on every slide through the CSS Highlight API, so the marks show in Chrome, Safari and an embedded pane alike; the browser's own checker adds the row you type in; never present, print or PDF; a name goes in the model's spell.ignore) · file: save a copy (only when the browser blocks storage) · PDF (⤓) · view: contact sheet (grid icon; C or Esc) · full screen (F) · shortcuts (ⓘ; a three-column popover: slides · rows · file; ⌘P and ⌘D are not shortcuts — the PDF and duplicate buttons are the only doors).This manifest is a contract: the gate compares it against the template, so the HUD cannot gain or lose a control without this line changing. While presenting, the HUD peeks back as a centred pill above the bottom edge — never over the page counter in the corner. On the contact sheet the HUD stays, pinned above the thumbnails, with prev/next/present disabled (the sheet is the navigator) and + adding a slide after the current one. Drag to move (a connector travels whole — both ends and every control point; a group travels whole and wears one dashed box), ⌘-click to multi-select (or to take one member of a group alone), drag from empty canvas for a marquee that takes every row it wholly contains (⇧ adds to the selection), double-click to retype, corner nib to resize, a connector's point nibs move one end (or a curve's control point) while a drag on its shaft moves it whole, ⌘Z to undo (persists across reloads), ⌘B / ⌘I / ⌘U mark a text selection or a whole selected row. Selecting text shows a floating toolbar: role segment, B / I / U / S̶ / link (marks never change size; the link takes http, https or mailto — an empty field unlinks), the deck's own colours as swatches, "Apply to all slides".
3. Contact sheet: live thumbnails 3-across; click / ⌘ / shift select, double-click opens, grab-and-drag reorders (mouse or touch — the other cells slide aside), ⌫ deletes (never the last), ⌘C ⌘V ⌘D ⌘Z. It also opens in present mode.
4. PDF: links become real /Link annotations, so a LinkedIn document post is clickable. Agents make PDFs one way: node bin/pdf.mjs deck.html [out.pdf] — the deck's own print pipeline through Chromium's print engine with a pixel @page, so every page is the slide's size (1 px = 0.75 pt), text stays text, fonts embed, and the HUD is hidden by the deck's @media print (never by an ad-hoc override). It gates itself (exit 1): pages == slides, page ratio == W/H, #hud computed display:none under print media, link annotations == linked rows. Screenshots stitched into a PDF (Playwright + ImageMagick) are an anti-pattern: raster text blurs on every rescale, carries no links, and shipped the HUD once. The PDF button takes the same route in Chromium — @page{size:W H px} + zoom:1 injected, then the browser's print dialog, where the user picks "Save as PDF"; afterprint removes the rule. Safari ignores px @page sizes, so there the button keeps the in-file rasteriser: each slide from its live DOM (SVG foreignObject → canvas at 3× → lossless RGB FlateDecode via CompressionStream; a page whose deflate exceeds 6 MB drops to JPEG .92) onto a W×H pt page — no letterboxing, no JPEG ringing; verified in WebKit. If rasterising throws or the canvas is tainted, it falls back to print(). ⌘P is the paper path: one page per slide on a named page size — Letter (A4 for document-a4) — the slide zoomed to the printable width.
5. Presenting: F or the fullscreen button; chrome hides, backdrop = current slide's background, HUD peeks back when the pointer rests at the bottom edge and stays pinned while the + menu, the text toolbar or the contact sheet is open. Arrow keys / space advance; Esc opens the contact sheet to jump.
6. Persistence, honestly. Every edit autosaves to the browser's storage under deck.id, and is appended to the in-file edit log (slide id, row id, keys before → after). ⌘S saves the deck file itself: in Chrome/Edge the first ⌘S asks for the file once (File System Access, remembered per browser), then every save — ⌘S and autosave alike — rewrites it in place with the model, the log and the versions inside, so an agent reading the file sees exactly what the human did. The dot is green only when the file has everything; amber counts the edits that have not reached it. Safari (and any browser without File System Access) cannot write the file: there ⌘S downloads a self-contained copy, and on file:// Safari blocks storage entirely — the dot goes red at load and the Save-a-copy button appears. A live text edit or a drag in flight is committed when the tab hides or unloads, so a refresh mid-edit loses nothing. Position: a new window opens on slide 1; a refresh, and a new version of the file, keep the slide you were on — by slide id, so inserting slides above does not move you. A stored working copy is trusted only on the same rev; a newer file wins as the base and the browser replays its own edit log onto it (human wins, conflicts flagged on the entries), so an agent's rewrite neither hides its changes nor drops the human's. Versions: the history control lists every version in the file — one per agent write (create --from), one per ⌘S, one per pin — and restores any of them (the state you leave is pinned first, so a restore is reversible). Capped at 20.
7. To revise an edited deck, run node bin/edits.mjs deck.html to read the log, then create --from deck.html (Step 4). Everything a human applies in the editor — geometry, text, links, arrows — round-trips that way; the console copy(JSON.stringify(deck)) still works for a raw model.
8. What you inferred (style, layout choices) and anything marked experimental.

MODEL CONTRACT

Top level:

Slot geometry: {x, y, w, h?, role} — or right in place of x; a slotted row's own right overrides the slot's x the way its own x would.

Slide: {id?, name?, layout?, bg?, hide?: masterId[], els: row[]} — id (unique per deck; s1, s2… when create stamps it) is how a tab remembers the slide it was on and how the edit log addresses a slide. Rows carry id (unique per slide; r1, r2…) for the same reason and for to:/from:.

Row — every prop optional; a row is whatever its props make it:

Resolution order for any row: slot geometry ← master row (for override rows) ← the row's own props ← role treatment. The role fills whatever the row left unset and always wins font/size/lh/ls — a row can never change family, size, leading or tracking.

STYLE CONTRACT (style.json)

{
  "tokens": { "bg": "#111315", "fg": "#F3F4F6", "muted": "#9CA3AF", "accent": "#5B9CF6", "card": "#1A1D21", "line": "#2C3138", "sel": "#5B9CF6", "box": "#20262E" },
  "roles": {
    "Title": { "font": "…", "size": 64, "weight": 800, "lh": 68, "ls": -1.5, "color": "var(--fg)" },
    "Supertitle": { "font": "ui-monospace,Menlo,monospace", "size": 12, "weight": 500, "lh": 16, "ls": 1.5, "color": "var(--accent)", "tt": "uppercase" },
    "H1":   { "font": "…", "size": 34, "weight": 800, "lh": 40, "ls": -0.5, "color": "var(--fg)" },
    "H2":   { "font": "…", "size": 22, "weight": 600, "lh": 28, "ls": -0.3, "color": "var(--fg)" },
    "Body": { "font": "…", "size": 16, "weight": 400, "lh": 24, "ls": 0, "color": "var(--fg)" },
    "Caption": { "font": "…", "size": 13, "weight": 400, "lh": 18, "ls": 0, "color": "var(--muted)" },
    "Label": { "font": "ui-monospace,Menlo,monospace", "size": 11, "weight": 500, "lh": 14, "ls": 1, "color": "var(--muted)", "tt": "uppercase" },
    "Stat":  { "font": "…", "size": 40, "weight": 800, "lh": 44, "ls": -1, "color": "var(--accent)" }
  },
  "pad": { "chip": "3px 8px", "pill": "5px 12px" },
  "margin": 60,
  "gap": 4
}

• tokens → CSS custom properties on :root. bg is the editor chrome behind the slide; card is the slide surface; box the outlined-box fill; sel the selection colour.
• The eight roles are the whole type system — exactly these names: Title (display headline for cover/closing slides), Supertitle (kicker), H1 (content-slide title), H2, Body, Caption, Label (mono, uppercase — chips, axis labels, footer), Stat. No H3, no Subtitle. One allowance: Stat2, an optional ninth role for the KPI tile — a hero "63%" and a card "$1.2M" cannot share one size. A style may define it; when it does not, create derives it from Stat at 0.6 (size, line height, tracking) and only when a row or slot asks for it, so a deck that never uses Stat2 never carries it. The kpi-grid tiles wear it; the hero stat layout keeps Stat. A role is a complete treatment: font, size, weight, lh, ls, color, optional tt. One font and one size per role — never two sizes of "Body". A row may add weight, color, tt, italic; it can never carry font, size, lh, ls or mono (the validator rejects it, the engine ignores it).
• margin is the content inset the chrome sits on (footer counter's right edge, default 6% of w). Set it to match your layouts' left edge.
• gap is the air every row owes its neighbours (default 4px, the offset the chart library itself uses between a bar and its value). Raise it for a roomier deck; validate enforces it on declared boxes.
• cw on a role is the measured average glyph width in em (width / chars / size of a representative sentence in that font, weight and case). validate sizes w:'auto' rows and line counts with it; without it the blanket 0.55 stands, which runs ~20% wide on a sans and ~20% narrow on an uppercase mono. Measure once per brand font in Chromium and put it in style.json; the neutral roles carry theirs.
• The model's own styles.roles win over style.json per role; a model with no roles inherits the template's neutral scale.

LAYOUTS (slots)

• layouts.<name>.<slot> = {x, y, w, h?, role}; a slide opts in with layout:'<name>'.
• slots.<slot> (deck scope) applies under every layout — use it for a supertitle shared by all.
• A slotted row may carry local x/y/w/h overrides; edit the slot in the model to move every slide at once.
• Conventional slot names: supertitle, title, body, body2. Conventional layouts: title (cover), content, section.
• A slot may carry any row treatment besides geometry and role — tile:1, bg, p:'chip', align, nowrap, italic, even line — and the engine spreads it onto the bound row. A roleless slot with h is paint or media: {slot:'rule'} alone draws it.

LAYOUT LIBRARY

Thirty-one named layouts ship with the engine (lib/layouts.mjs), in the same shape as a layouts entry. Name one on a slide the deck does not define and create merges it into deck.layouts, scaled from its 960×540 cut to the canvas (1600×900 = ×1.67). Print the catalogue — name, group, density, use, slots — with:

node bin/validate.mjs --layouts

Read that instead of inventing geometry. The library is an accelerant, never a fence: a slide may use a library layout, a deck-defined layout, or free rows, and may mix library slots with extra free rows on the same slide (layout:'kpi-grid' plus a caption and a rule at y 400 is a normal slide). A deck-defined layout of the same name wins. A slotted row still takes its own x/y/w/h — the override path — so a brand with a display role taller than the neutral scale (Title 64/68, Stat 40/44 — what the library is cut for) nudges a slot without redefining the layout. An unknown name is still an error, and the error lists the library.

Density is defined in DENSITY below: a speaker (fluffy) slide carries ≤ 3 points, a reading (dense) slide up to 8 with its own context. Every layout with H1 title chrome also carries the four dense slots subtitle · note · source · legend (unbound they draw nothing). Delta chips are Label on a chip pad in var(--box), coloured var(--ok, var(--accent)); a falling delta sets color:'var(--bad, var(--accent))' on the row — the deck's ok/bad tokens if the style defines them, else the accent.

Picking a layout by what the content is:

TEMPLATE LIBRARY

Fifty-nine finished slides ship with the engine (lib/templates.mjs, sources in lib/templates/cat-*.mjs): the candidate sheet surveyed across the open-source slide catalogs and promoted whole (2026-09-07). A template is a layout PLUS sample rows — an issue tree, a Sankey, a scorecard, a bento grid — so the agent binds content instead of drawing. Print the catalogue — id · tier · density · note, then every text key with its sample — with:

node bin/validate.mjs --templates

A slide names one and fills its keys: {template: 'three-up-cards', fill: {t1: 'What you get', t2: 'Three things, one price.', t3: '01', …}}. Every text row of the template is a key, t1…tn in row order; a key left out keeps the sample text (so fill them all before shipping). create expands the slide into the template's rows, scaled from the 960×540 cut to the canvas, sets the slide's layout to the template's chrome (content or title from the library — a deck-defined layout of that name wins) and its density, and keeps any free els after the template rows. An unknown template or fill key is a validate error listing what exists. A template is an accelerant like a layout: edit the rows it produced, add rows beside them, or draw free — nothing here is a fence. Tiers: core (in 4+ surveyed catalogs), standard (consulting catalogs), fringe (dataviz literature, rare on slides). Categories: Narrative · Numbers · Comparison · Frameworks · Process · Charts · Modern.

DENSITY

Two named densities, defined in lib/layouts.mjs (DENSITY) so "dense" and "fluffy" build the same deck every time. A deck says density: 'speaker' | 'reading'; a slide may carry its own. validate warns on every slide that misses its density's shape; an unknown density is an error.

GRAPHICS

Five kinds of picture, one rule each. Colour is always a token; nothing loads from the network.

• Icons — {icon: 'shield-check', x, y, w: 24, h: 24, color: 'var(--accent)'}. The set is Lucide (ISC), 169 names, node bin/validate.mjs --icons prints them; create inlines the svg (stroke currentColor, so color paints it) and only the icons a deck uses reach the file. One icon per point, on the 24 grid (24/32/40 px), left of its label on the label's cap line, the same weight throughout. An icon says what the label says — never decoration, never a second idea, never a filled emoji.
• Glyphs — a number in a circle, a letter chip, a status dot: rows, not images. A step glyph is a dot (or a radius:'50%' box) with a Label centred in it (valign:'middle'); a status dot is a 10px bg circle in var(--ok)/var(--bad). Group the glyph with its text.
• Images — img is a data: URI, fit:'cover', explicit w/h, one per slide, never stretched, never behind text unless a tint band (bg with op) sits between. Budget ≈ 100 KB an image, the file under ~1 MB. Photographs carry the image-left/image-right/image-hero-overlay/image-split layouts; a screenshot gets annotated-shot with callout rows.
• Figures — nodes, connectors, timelines, trees as rows (the diagram helper, the diagram layout, the framework and process templates), so every box and edge stays editable. An svg row is for a fill the engine has no primitive for (a Sankey ribbon, an area band) — never for text, never for a whole figure.
• Clips — a short

…(truncated)