d2-slides
Paths below: <skill> is this skill's directory and <skills> the directory the skills are
installed in (skills/ in mizchi/explainer, .claude/skills/ in a project that installed them).
A deck is text: the prose is Markdown, every figure is a ```d2 fence, and the
build is a pure function of the file. Nothing is dragged, so a slide can be
reviewed in a diff, regenerated after a rename, and — because the output is an
HTML page — checked. That last part is the point: a slide deck normally has
no failing state, so nobody notices the bullet the frame cut in half.
node <skill>/assets/build-deck.mjs deck.md --out built
# ✓ built/index.html: 8 slides, 5 figure(s) laid out by tala, 26 copy lines → built/copy.txt
# the deck: built/index.html → vlmkit check integrity
# all slides: built/print.html → vlmkit check copy --manifest, check a11y contrast, print to PDF
Requires d2 with TALA (d2 layout must list tala (bundled) — see
d2-diagram for installing it) and nothing else: the builder has no
dependencies and the deck loads no network resource.
The deck format
---
title: Nothing tells you the picture is wrong
subtitle: two rounds, measured
date: 2026-09-14
---
# Nothing tells you the picture is wrong ← a lone `#` heading is the title slide
---
## A D2 diagram is a drawing ← `##` is a slide heading
- `d2 validate` reads **syntax** ← bullets; `code`, **bold**, *italic* work
- there is no `--expect`
```d2 ← the figure, laid out by TALA
direction: right
write -> check -> facts
```
<!-- notes: what to say out loud --> ← speaker notes: printed, never on screen
- Slides are separated by a line of exactly
---; a --- inside a fence is not
a separator.
- Bullets plus a figure lays them side by side; a figure alone gets the
whole stage; a heading alone is a title slide.
> line is a pull quote, and a
fence in any other language stays a code block.
- Each slide is a fixed 1280×720 frame, scaled to whatever screen it is
shown on. Nothing reflows between a laptop and a projector, which is also why
a screenshot of slide 4 is the same picture everywhere.
The loop
1. write deck.md prose in Markdown, every figure a ```d2 fence
2. node …/build-deck.mjs deck.md --out built fails on the first figure that does not compile,
naming the slide; warns when a slide's prose
overflows its frame's character budget
3. vlmkit check integrity built/index.html a slide that breaks, clips, collides or paints nothing
4. vlmkit check integrity built/print.html --viewports 1280
every slide at once — this is what catches the
bullet the frame cut off
5. vlmkit check copy built/print.html --manifest built/copy.txt --allow-invisible unknown
every line of the deck's own text still on a slide
(add --forbid stale.txt when you are editing a deck:
the claim you removed must really be gone)
6. vlmkit check a11y contrast built/print.html readable from the back of the room
7. node …/d2-facts.mjs --from-svg built/slide-NN.svg --expect slide-NN.facts.json
what each figure DRAWS, for every figure that has
facts it must not get wrong — steps 3-6 are blind to it
8. node …/deck-review.mjs built --out review shoot each slide, hand the PNGs to a reader
node …/deck-review.mjs built --answers a.json score what it read back: fidelity, order, SPLITs
9. read built/index.html in a browser, or the PNG of a slide; fix the Markdown; go to 2
Step 7 is not optional decoration, and the four page gates do not cover it.
They read the page: a figure that compiles and draws the wrong thing passes all
four. The checker takes the slide SVGs the build already writes and needs no
d2 (it reads the render), so this costs one command per figure:
node <skills>/d2-diagram/assets/d2-facts.mjs --from-svg built/slide-04.svg \
--expect slide-04.facts.json # exits 1 and names the box or edge that is wrong
The same trick pins two figures to each other, which nothing else does: when
slides 2 and 3 both claim ledger is the writer, hold both SVGs to one sheet
({"boxes": ["checkout","ledger"], "deps": ["checkout->ledger"], "forbidden": ["checkout->orders"]}).
Update one figure and forget the other and that sheet fails on the one you
missed. The fact-sheet schema is d2-diagram's; exhaustive: true is what makes
an extra box an error rather than a shrug.
Step 8: somebody has to read it
Steps 3-7 are the page and the figures' geometry. None of them reads the slide
the way a viewer does, and that gap is not theoretical: in the v1/v2 rounds two
defects reached a delivered deck — a sentence rendered as two blocks, and a
fragment sitting above its own bullet — with all four gates green, because
every fragment was visible text and nothing overflowed.
node <skill>/assets/deck-review.mjs built --out review
# → review/slide-NN.png, one per slide, plus review-brief.md
# hand that directory to a vision model or an agent; it answers JSON
node <skill>/assets/deck-review.mjs built --answers review/answers.json
# read 19/21, invented 6, fidelity 0.70, order 1.00
# ⚠ SPLIT: "…it calls ledger, which is now the only writer to orders."
# every word is on the slide, the sentence is not — read back as 2 blocks
The scoring is deterministic, against the slides.json the build writes: each
slide's text in reading order (which copy.txt is not — the manifest is a
set, and it lists bullets before paragraphs while the page renders paragraphs
first) plus the words its figures draw.
Two numbers and one line to read:
- fidelity — sheet lines read / (sheet lines + invented). 1.00 is "the
slide, nothing more". Measured in v3: 1.00 on a clean deck from both readers,
0.70 on the same deck built by a builder that split its bullets.
- order — pairs of read lines whose order disagrees with the sheet. It is
for a genuinely reordered slide; be aware it did not catch v3's split,
because the fragments still appeared in the sheet's relative order. Fidelity
and the SPLIT line caught that.
- ⚠ SPLIT — a sheet line no single read line covers, whose words are all
present across two or more. That is one sentence rendered as two blocks, and
the tool names it whether or not the reader had the word for it: one v3
reader called the same defect "clipped at the right edge" — right slides,
wrong mechanism — and the diagnosis came out anyway.
--sheet <other-build>/slides.json scores one render against another build's
sheet, which is how a before/after pair is compared against one ground truth.
Honest limits. A reader that transcribes none of the figures' labels is not
evidence they are illegible, only that it read prose — the figures: k of n
line is a hint, not a verdict. A reading is a measurement and exits 0; what to
do about a 0.7 is the author's call. And a reader will occasionally report a
mechanism that is not the real one, so read the slide it names before believing
the reason it gives.
Done condition
- The build exits 0 with no overflow warning.
check integrity reports no failures on index.html (all three
viewports) and on print.html at 1280. A warn is not a failure and the
command still exits 0 — see the figure-internals note below before you spend
a round chasing one.
check copy --manifest reports nothing missing (and nothing forbidden, if
you are editing an existing deck).
check a11y contrast reports no failure, over a count that means every
slide was read. The count is content-dependent — a terse deck runs about 7
elements a slide, a dense one about 17 — so the number is not the test. Run
it against index.html too: that shows one slide at a time, so it comes back
in single digits. Print view ≫ deck view is the check.
- Every figure with facts it must not get wrong passed
d2-facts --expect.
- Somebody read it back. You pressed through the deck yourself, or a reader
scored it with
deck-review — fidelity near 1.00 and no SPLIT. This is the
only step that sees a sentence broken into two blocks.
The same loop, in CI
This repo runs its own worked example through that loop on every change to the skill,
the example or the three gates it uses, so the claim above is measured rather than
asserted. Two halves, because they need different machines:
tests/d2/d2-slides.test.mjs (in the ordinary suite, no d2, no browser) — the
builder's decisions before a figure is drawn: where a slide ends (--- inside a
fence is not a separator), which layout a slide gets, the manifest as the rendered
text, the overflow warning naming the slide, a figure that does not compile failing
the build, and examples/d2-slides/built/ still matching its deck.md. D2 points
at a stub that echoes a fixed SVG — the builder already reads that variable.
.github/workflows/d2-slides.yml (real d2 pinned at v0.9.0, real Chromium) —
the four gate runs above on a fresh build, plus a byte comparison against the
committed build, plus two negative controls: a manifest line the deck does not say
must be reported copy-missing, and a frame shortened to 260px must be reported
clipped-content. A suite that only ever sees passes cannot tell a working gate from
a gate that always passes.
Regenerate the committed example with npm run deck:example after editing its deck.md —
the byte comparison is what keeps a committed build from drifting into a lie.
What the gates found in this skill's own deck
Everything below was a real defect in the template or the example, caught by a
gate, fixed, and re-measured. It is why the loop above is in that order.
- A phone showed nothing.
check integrity at 375px: "the DOM holds 4 text
blocks but almost nothing painted (ink ratio 0.05%)". Centring a 1280px stage
as an over-sized grid item leaves the middle off-screen; the stage is centred
by transform now.
- Every slide clipped 114px. A percentage height inside a padded fixed box
is not the box: the frame is a flex column and the body the flexible child.
The gate reported it as
clipped-content on slides whose text was well inside
the frame.
- Long bullets were cut top and bottom. With
align-items: center on the
split layout, prose taller than the frame overflows both ways and the copy
gate reads those lines as copy a user cannot see. Overflow goes downward now,
where it is measurable, and the builder warns above ~430 characters of prose
beside a figure.
- The manifest did not match the render. It is generated from the rendered
markup, not from the Markdown with its markers stripped: a line containing
```d2 strips to something the page never says.
What the copy manifest covers
copy.txt is generated from the Markdown prose only — each slide's
heading, bullets, pull quotes and paragraphs, as the page renders them
(markers gone, entities decoded). Three things are therefore not in it:
- A figure's labels. Text inside a ```d2 fence is drawn as SVG, and the
manifest never contains it. So a string the deck must be seen to say belongs
in prose; if it only appears in a figure, the copy gate cannot vouch for it —
hold the figure to a fact sheet instead (step 7).
- Speaker notes.
<!-- notes: … --> is printed and never on screen, and it
is not in the manifest either.
- The chrome. The footer's deck title and page number are not manifest
lines.
For a reader, the build also writes slides.json: per slide, its heading,
its text in reading order, its figures and the words those figures draw. That
is the sheet deck-review scores against, and the reason it is a separate file
from copy.txt is that a manifest cannot express order.
A bullet, quote or paragraph wrapped over several lines is rejoined into one
line, as Markdown does, so wrapping at 80 columns is safe and one sentence is
one manifest line. A blank line ends the block: an indented line after one is a
paragraph of its own.
Failure modes
✗ slide 6-1: the d2 figure does not compile with
reserved keywords are prohibited in edges → an id collided with a D2
keyword. width, height, label, style, shape, icon, near, top,
left, direction, class, link, constraint, layers, steps and
scenarios are the ones that bite; rename the box (cols, verdict) and
keep the words in its label.
copy-invisible (reason: unknown) on a line that is plainly on the slide
→ a vlmkit gate limitation, not your deck: a manifest line whose rendered text
is assembled from several inline children can read as invisible. Reproduced
minimally in examples/d2-slides/README.md; three bullets carrying <code>
and <strong> fail, the same three lines without markup pass. Run with
--allow-invisible unknown (every accepted line is listed, so the suppression
stays auditable) and check the missing count, which is the part that matters.
check a11y contrast inspected only four elements → you pointed it at
index.html. One slide is on screen at a time; print.html is the stacked
view. Do not read the absolute count as a threshold: it tracks how many text
nodes the deck has, so a terse deck legitimately sits near 7 a slide. The
comparison between the two views is the signal.
near-misalignment (a warn) on a base64-looking selector like
g.KGdhdGV3YXkgLSZndDsgY2hlY2tvdXQpWzBd → that is inside a figure's SVG:
the gate has found two of TALA's own edge-label groups sitting 5.5px apart,
which is the layout engine's business and not the deck's. It is a warn, so
the verdict reads NO DEFECTS, n WARN and the command exits 0 — that is
done, leave it. There is no stable way to exempt it either: --allow matches
the finding's own selector by substring, and d2 derives that class from the
edge's text, so the string changes with the label. If a run has to be silent,
--rule near-misalignment=off is the only lever, and it gives up the rule for
the slide chrome too. Whether it fires at all depends on the layout, not on
having labelled edges: the same deck's figures can be CLEAN after an edit.
page-overflow-x on print.html at 768 or 375 → expected: the print view
is a column of 1280px frames. Check it at --viewports 1280.
- A figure is enormous or unreadable → it is a D2 diagram like any other:
take it to
d2-diagram, where the width levers, the fact check and the
terminal render live. A slide figure has about 700×560 to live in.
- CJK labels render correctly in SVG, so a Japanese deck is fine; the
terminal-render caveats in
d2-diagram do not apply here.
Deliver
- The deck:
built/index.html, opened in a browser. Arrows and space move, o
is the overview grid, p prints, f is fullscreen, and the URL carries
#/4, so one slide can be linked.
- A PDF: open
print.html and print it, or index.html and press p. Speaker
notes appear in print and never on screen.
- In a repo: commit
deck.md and the figures' .svg; the HTML is a build
output. examples/d2-slides/ is the worked example — its deck, its build, and
the gate runs above.
- One slide as an image: the figure is already
built/slide-NN.svg.
1---2description: 'Build a slide deck whose source is text and whose figures are laid out by TALA — one Markdown file with a ```d2 fence per figure, compiled to a self-contained HTML deck (keyboard nav, overview grid, print-to-PDF), each figure as its own SVG, and a copy manifest. The deck is a page, so vlmkit''s own gates read it: `check integrity` for a slide that breaks or clips, `check copy --manifest` for text the frame cut off, `check a11y contrast` for a projector. Loop: write `deck.md` → build → gates → fix. Use when asked for slides, a deck, a talk, a presentation, a review walkthrough, or a figure-heavy explainer that has to be presented rather than read. Not for one diagram (`d2-diagram`) or a moving figure (`explanatory-animation`).'3metadata:4 source: https://skillmd.com/skills/h3y6e/d2-slides5 github-path: skills/d2-slides6 github-ref: refs/heads/main7 github-repo: https://github.com/mizchi/explainer8 github-tree-sha: 1f45605eb0994490581cb37e8aef6eeee15e73829name: d2-slides10---1112# d2-slides1314Paths below: `<skill>` is this skill's directory and `<skills>` the directory the skills are15installed in (`skills/` in mizchi/explainer, `.claude/skills/` in a project that installed them).1617A deck is text: the prose is Markdown, every figure is a ```d2 fence, and the18build is a pure function of the file. Nothing is dragged, so a slide can be19reviewed in a diff, regenerated after a rename, and — because the output is an20HTML page — **checked**. That last part is the point: a slide deck normally has21no failing state, so nobody notices the bullet the frame cut in half.2223```bash24node <skill>/assets/build-deck.mjs deck.md --out built25# ✓ built/index.html: 8 slides, 5 figure(s) laid out by tala, 26 copy lines → built/copy.txt26# the deck: built/index.html → vlmkit check integrity27# all slides: built/print.html → vlmkit check copy --manifest, check a11y contrast, print to PDF28```2930Requires `d2` with TALA (`d2 layout` must list `tala (bundled)` — see31`d2-diagram` for installing it) and nothing else: the builder has no32dependencies and the deck loads no network resource.3334## The deck format3536````markdown37---38title: Nothing tells you the picture is wrong39subtitle: two rounds, measured40date: 2026-09-1441---4243# Nothing tells you the picture is wrong ← a lone `#` heading is the title slide4445---4647## A D2 diagram is a drawing ← `##` is a slide heading4849- `d2 validate` reads **syntax** ← bullets; `code`, **bold**, *italic* work50- there is no `--expect`5152```d2 ← the figure, laid out by TALA53direction: right54write -> check -> facts55```5657<!-- notes: what to say out loud --> ← speaker notes: printed, never on screen58````5960- Slides are separated by a line of exactly `---`; a `---` inside a fence is not61 a separator.62- **Bullets plus a figure** lays them side by side; **a figure alone** gets the63 whole stage; a heading alone is a title slide. `> line` is a pull quote, and a64 fence in any other language stays a code block.65- Each slide is a fixed **1280×720 frame**, scaled to whatever screen it is66 shown on. Nothing reflows between a laptop and a projector, which is also why67 a screenshot of slide 4 is the same picture everywhere.6869## The loop7071```721. write deck.md prose in Markdown, every figure a ```d2 fence732. node …/build-deck.mjs deck.md --out built fails on the first figure that does not compile,74 naming the slide; warns when a slide's prose75 overflows its frame's character budget763. vlmkit check integrity built/index.html a slide that breaks, clips, collides or paints nothing774. vlmkit check integrity built/print.html --viewports 128078 every slide at once — this is what catches the79 bullet the frame cut off805. vlmkit check copy built/print.html --manifest built/copy.txt --allow-invisible unknown81 every line of the deck's own text still on a slide82 (add --forbid stale.txt when you are editing a deck:83 the claim you removed must really be gone)846. vlmkit check a11y contrast built/print.html readable from the back of the room857. node …/d2-facts.mjs --from-svg built/slide-NN.svg --expect slide-NN.facts.json86 what each figure DRAWS, for every figure that has87 facts it must not get wrong — steps 3-6 are blind to it888. node …/deck-review.mjs built --out review shoot each slide, hand the PNGs to a reader89 node …/deck-review.mjs built --answers a.json score what it read back: fidelity, order, SPLITs909. read built/index.html in a browser, or the PNG of a slide; fix the Markdown; go to 291```9293**Step 7 is not optional decoration, and the four page gates do not cover it.**94They read the page: a figure that compiles and draws the wrong thing passes all95four. The checker takes the slide SVGs the build already writes and needs no96`d2` (it reads the render), so this costs one command per figure:9798```bash99node <skills>/d2-diagram/assets/d2-facts.mjs --from-svg built/slide-04.svg \100 --expect slide-04.facts.json # exits 1 and names the box or edge that is wrong101```102103The same trick pins **two figures to each other**, which nothing else does: when104slides 2 and 3 both claim `ledger` is the writer, hold *both* SVGs to one sheet105(`{"boxes": ["checkout","ledger"], "deps": ["checkout->ledger"], "forbidden": ["checkout->orders"]}`).106Update one figure and forget the other and that sheet fails on the one you107missed. The fact-sheet schema is `d2-diagram`'s; `exhaustive: true` is what makes108an extra box an error rather than a shrug.109110## Step 8: somebody has to read it111112Steps 3-7 are the page and the figures' geometry. None of them reads the slide113the way a viewer does, and that gap is not theoretical: in the v1/v2 rounds two114defects reached a **delivered** deck — a sentence rendered as two blocks, and a115fragment sitting above its own bullet — with all four gates green, because116every fragment was visible text and nothing overflowed.117118```bash119node <skill>/assets/deck-review.mjs built --out review120# → review/slide-NN.png, one per slide, plus review-brief.md121# hand that directory to a vision model or an agent; it answers JSON122node <skill>/assets/deck-review.mjs built --answers review/answers.json123# read 19/21, invented 6, fidelity 0.70, order 1.00124# ⚠ SPLIT: "…it calls ledger, which is now the only writer to orders."125# every word is on the slide, the sentence is not — read back as 2 blocks126```127128The scoring is deterministic, against the `slides.json` the build writes: each129slide's text **in reading order** (which `copy.txt` is not — the manifest is a130set, and it lists bullets before paragraphs while the page renders paragraphs131first) plus the words its figures draw.132133Two numbers and one line to read:134135- **fidelity** — sheet lines read / (sheet lines + invented). 1.00 is "the136 slide, nothing more". Measured in v3: 1.00 on a clean deck from both readers,137 0.70 on the same deck built by a builder that split its bullets.138- **order** — pairs of read lines whose order disagrees with the sheet. It is139 for a genuinely reordered slide; be aware it did **not** catch v3's split,140 because the fragments still appeared in the sheet's relative order. Fidelity141 and the SPLIT line caught that.142- **⚠ SPLIT** — a sheet line no single read line covers, whose words are all143 present across two or more. That is one sentence rendered as two blocks, and144 the tool names it whether or not the reader had the word for it: one v3145 reader called the same defect "clipped at the right edge" — right slides,146 wrong mechanism — and the diagnosis came out anyway.147148`--sheet <other-build>/slides.json` scores one render against another build's149sheet, which is how a before/after pair is compared against one ground truth.150151Honest limits. A reader that transcribes none of the figures' labels is not152evidence they are illegible, only that it read prose — the `figures: k of n`153line is a hint, not a verdict. A reading is a measurement and exits 0; what to154do about a 0.7 is the author's call. And a reader will occasionally report a155mechanism that is not the real one, so read the slide it names before believing156the reason it gives.157158## Done condition159160- The build exits 0 with no overflow warning.161- `check integrity` reports **no failures** on `index.html` (all three162 viewports) and on `print.html` at 1280. A `warn` is not a failure and the163 command still exits 0 — see the figure-internals note below before you spend164 a round chasing one.165- `check copy --manifest` reports nothing missing (and nothing forbidden, if166 you are editing an existing deck).167- `check a11y contrast` reports no failure, over a count that means **every**168 slide was read. The count is content-dependent — a terse deck runs about 7169 elements a slide, a dense one about 17 — so the number is not the test. Run170 it against `index.html` too: that shows one slide at a time, so it comes back171 in single digits. Print view ≫ deck view is the check.172- Every figure with facts it must not get wrong passed `d2-facts --expect`.173- **Somebody read it back.** You pressed through the deck yourself, or a reader174 scored it with `deck-review` — fidelity near 1.00 and no `SPLIT`. This is the175 only step that sees a sentence broken into two blocks.176177## The same loop, in CI178179This repo runs its own worked example through that loop on every change to the skill,180the example or the three gates it uses, so the claim above is measured rather than181asserted. Two halves, because they need different machines:182183- **`tests/d2/d2-slides.test.mjs`** (in the ordinary suite, no `d2`, no browser) — the184 builder's decisions before a figure is drawn: where a slide ends (`---` inside a185 fence is not a separator), which layout a slide gets, the manifest as the *rendered*186 text, the overflow warning naming the slide, a figure that does not compile failing187 the build, and `examples/d2-slides/built/` still matching its `deck.md`. `D2` points188 at a stub that echoes a fixed SVG — the builder already reads that variable.189- **`.github/workflows/d2-slides.yml`** (real `d2` pinned at `v0.9.0`, real Chromium) —190 the four gate runs above on a fresh build, plus a byte comparison against the191 committed build, plus two negative controls: a manifest line the deck does not say192 must be reported `copy-missing`, and a frame shortened to 260px must be reported193 `clipped-content`. A suite that only ever sees passes cannot tell a working gate from194 a gate that always passes.195196Regenerate the committed example with `npm run deck:example` after editing its `deck.md` —197the byte comparison is what keeps a committed build from drifting into a lie.198199## What the gates found in this skill's own deck200201Everything below was a real defect in the template or the example, caught by a202gate, fixed, and re-measured. It is why the loop above is in that order.203204- **A phone showed nothing.** `check integrity` at 375px: *"the DOM holds 4 text205 blocks but almost nothing painted (ink ratio 0.05%)"*. Centring a 1280px stage206 as an over-sized grid item leaves the middle off-screen; the stage is centred207 by transform now.208- **Every slide clipped 114px.** A percentage height inside a padded fixed box209 is not the box: the frame is a flex column and the body the flexible child.210 The gate reported it as `clipped-content` on slides whose text was well inside211 the frame.212- **Long bullets were cut top and bottom.** With `align-items: center` on the213 split layout, prose taller than the frame overflows both ways and the copy214 gate reads those lines as copy a user cannot see. Overflow goes downward now,215 where it is measurable, and the builder warns above ~430 characters of prose216 beside a figure.217- **The manifest did not match the render.** It is generated from the rendered218 markup, not from the Markdown with its markers stripped: a line containing219 ```` ```d2 ```` strips to something the page never says.220221## What the copy manifest covers222223`copy.txt` is generated from the **Markdown prose only** — each slide's224heading, bullets, pull quotes and paragraphs, as the page renders them225(markers gone, entities decoded). Three things are therefore *not* in it:226227- **A figure's labels.** Text inside a ```d2 fence is drawn as SVG, and the228 manifest never contains it. So a string the deck must be seen to say belongs229 in prose; if it only appears in a figure, the copy gate cannot vouch for it —230 hold the figure to a fact sheet instead (step 7).231- **Speaker notes.** `<!-- notes: … -->` is printed and never on screen, and it232 is not in the manifest either.233- **The chrome.** The footer's deck title and page number are not manifest234 lines.235236For a reader, the build also writes **`slides.json`**: per slide, its heading,237its text in reading order, its figures and the words those figures draw. That238is the sheet `deck-review` scores against, and the reason it is a separate file239from `copy.txt` is that a manifest cannot express order.240241A bullet, quote or paragraph wrapped over several lines is **rejoined** into one242line, as Markdown does, so wrapping at 80 columns is safe and one sentence is243one manifest line. A blank line ends the block: an indented line after one is a244paragraph of its own.245246## Failure modes247248- **`✗ slide 6-1: the d2 figure does not compile`** with249 `reserved keywords are prohibited in edges` → an id collided with a D2250 keyword. `width`, `height`, `label`, `style`, `shape`, `icon`, `near`, `top`,251 `left`, `direction`, `class`, `link`, `constraint`, `layers`, `steps` and252 `scenarios` are the ones that bite; rename the box (`cols`, `verdict`) and253 keep the words in its label.254- **`copy-invisible (reason: unknown)` on a line that is plainly on the slide**255 → a vlmkit gate limitation, not your deck: a manifest line whose rendered text256 is assembled from several inline children can read as invisible. Reproduced257 minimally in `examples/d2-slides/README.md`; three bullets carrying `<code>`258 and `<strong>` fail, the same three lines without markup pass. Run with259 `--allow-invisible unknown` (every accepted line is listed, so the suppression260 stays auditable) and check the `missing` count, which is the part that matters.261- **`check a11y contrast` inspected only four elements** → you pointed it at262 `index.html`. One slide is on screen at a time; `print.html` is the stacked263 view. Do not read the absolute count as a threshold: it tracks how many text264 nodes the deck has, so a terse deck legitimately sits near 7 a slide. The265 comparison between the two views is the signal.266- **`near-misalignment` (a warn) on a base64-looking selector like267 `g.KGdhdGV3YXkgLSZndDsgY2hlY2tvdXQpWzBd`** → that is *inside* a figure's SVG:268 the gate has found two of TALA's own edge-label groups sitting 5.5px apart,269 which is the layout engine's business and not the deck's. It is a `warn`, so270 the verdict reads `NO DEFECTS, n WARN` and the command exits 0 — that is271 done, leave it. There is no stable way to exempt it either: `--allow` matches272 the finding's own selector by substring, and d2 derives that class from the273 edge's text, so the string changes with the label. If a run has to be silent,274 `--rule near-misalignment=off` is the only lever, and it gives up the rule for275 the slide chrome too. Whether it fires at all depends on the layout, not on276 having labelled edges: the same deck's figures can be CLEAN after an edit.277- **`page-overflow-x` on `print.html` at 768 or 375** → expected: the print view278 is a column of 1280px frames. Check it at `--viewports 1280`.279- **A figure is enormous or unreadable** → it is a D2 diagram like any other:280 take it to `d2-diagram`, where the width levers, the fact check and the281 terminal render live. A slide figure has about 700×560 to live in.282- **CJK labels** render correctly in SVG, so a Japanese deck is fine; the283 terminal-render caveats in `d2-diagram` do not apply here.284285## Deliver286287- The deck: `built/index.html`, opened in a browser. Arrows and space move, `o`288 is the overview grid, `p` prints, `f` is fullscreen, and the URL carries289 `#/4`, so one slide can be linked.290- A PDF: open `print.html` and print it, or `index.html` and press `p`. Speaker291 notes appear in print and never on screen.292- In a repo: commit `deck.md` and the figures' `.svg`; the HTML is a build293 output. `examples/d2-slides/` is the worked example — its deck, its build, and294 the gate runs above.295- One slide as an image: the figure is already `built/slide-NN.svg`.